@elench/testkit 0.1.16 → 0.1.18

package/lib/runner/template.mjs

@@ -0,0 +1,320 @@
+import path from "path";
+
+const PORT_STRIDE = 100;
+
+export function resolveWorkerRuntimeConfigs(targetConfig, runtimeConfigs, workerId, workerStateDir) {
+  const portMap = buildPortMap(runtimeConfigs, workerId);
+  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
+    )
+  );
+}
+
+export function buildPortMap(runtimeConfigs, workerId) {
+  const portMap = new Map();
+  const seen = new Map();
+  const offset = PORT_STRIDE * (workerId - 1);
+
+  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;
+}
+
+export 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,
+      }
+    : 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,
+    },
+  };
+}
+
+export function resolveServiceStateDir(workerStateDir, targetName, config) {
+  const dbSource = config.testkit.databaseFrom || config.name;
+  return getWorkerServiceStateDir(workerStateDir, targetName, dbSource);
+}
+
+export function getWorkerServiceStateDir(workerStateDir, targetName, serviceName) {
+  if (targetName === serviceName) {
+    return workerStateDir;
+  }
+  return path.join(workerStateDir, "deps", serviceName);
+}
+
+export function buildExecutionEnv(config, extraEnv = {}, processEnv = process.env) {
+  const inheritedEnv = { ...processEnv };
+  const env = {
+    ...inheritedEnv,
+    ...(config.testkit.serviceEnv || {}),
+    ...extraEnv,
+    TESTKIT_ACTIVE: "1",
+    ...(config.workerId ? { TESTKIT_WORKER_ID: String(config.workerId) } : {}),
+  };
+  delete env.DATABASE_URL;
+  return env;
+}
+
+export function buildPlaywrightEnv(config, baseUrl, processEnv = process.env) {
+  return buildExecutionEnv(
+    config,
+    {
+      BASE_URL: baseUrl,
+      PLAYWRIGHT_HTML_OPEN: "never",
+      PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS:
+        processEnv.PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS || "1",
+      TESTKIT_MANAGED_SERVERS: "1",
+      TESTKIT_WORKER_ID: String(config.workerId),
+    },
+    processEnv
+  );
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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}` : ""}}"`);
+    }
+  });
+}
+
+export 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;
+  }
+}
+
+export function numericPortFromUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    const port = Number(url.port);
+    return Number.isInteger(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+export function socketFromUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port <= 0) return null;
+
+    const host = normalizeSocketHost(url.hostname);
+    return host ? { host, port } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeSocketHost(hostname) {
+  if (!hostname || hostname === "localhost") return "127.0.0.1";
+  if (hostname === "[::1]") return "::1";
+  return hostname;
+}

package/lib/runner/template.test.mjs

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildExecutionEnv,
+  buildPlaywrightEnv,
+  buildPortMap,
+  finalizeString,
+  getWorkerServiceStateDir,
+  normalizeSocketHost,
+  numericPortFromUrl,
+  resolveServiceStateDir,
+  resolveTemplateString,
+  resolveWorkerRuntimeConfigs,
+  rewriteUrlPort,
+  socketFromUrl,
+} from "./template.mjs";
+
+function makeRuntimeConfig(name, local, extras = {}) {
+  return {
+    name,
+    testkit: {
+      local,
+      serviceEnv: extras.serviceEnv || {},
+      databaseFrom: extras.databaseFrom,
+      migrate: extras.migrate,
+      seed: extras.seed,
+    },
+  };
+}
+
+describe("runner-template", () => {
+  it("builds port maps and detects collisions", () => {
+    const configs = [
+      makeRuntimeConfig("api", { port: 3000, baseUrl: "http://127.0.0.1:{port}" }),
+      makeRuntimeConfig("frontend", { port: 3001, baseUrl: "http://127.0.0.1:{port}" }),
+    ];
+
+    expect([...buildPortMap(configs, 2).entries()]).toEqual([
+      ["api", 3100],
+      ["frontend", 3101],
+    ]);
+
+    expect(() =>
+      buildPortMap(
+        [
+          makeRuntimeConfig("api", { port: 3000, baseUrl: "http://127.0.0.1:{port}" }),
+          makeRuntimeConfig("other", { port: 3000, baseUrl: "http://127.0.0.1:{port}" }),
+        ],
+        1
+      )
+    ).toThrow("Worker port collision");
+  });
+
+  it("resolves template strings and URL rewrites", () => {
+    const context = {
+      workerId: 2,
+      targetName: "frontend",
+      serviceName: "frontend",
+      serviceStateDir: "/tmp/state",
+      portMap: new Map([
+        ["frontend", 3200],
+        ["api", 3100],
+      ]),
+      baseUrlByService: new Map([["api", "http://127.0.0.1:3100"]]),
+      readyUrlByService: new Map([["api", "http://127.0.0.1:3100/health"]]),
+      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(finalizeString("API={baseUrl:api} OLD=http://api:3000", context)).toBe(
+      "API=http://127.0.0.1:3100 OLD=http://127.0.0.1:3100"
+    );
+    expect(rewriteUrlPort("http://127.0.0.1:3000/health", 3200)).toBe(
+      "http://127.0.0.1:3200/health"
+    );
+  });
+
+  it("builds worker runtime configs and execution env", () => {
+    const api = makeRuntimeConfig("api", {
+      cwd: ".",
+      start: "npm run api",
+      port: 3000,
+      baseUrl: "http://127.0.0.1:{port}",
+      readyUrl: "http://127.0.0.1:{port}/health",
+      env: {
+        PORT: "{port}",
+      },
+    }, {
+      serviceEnv: {
+        API_KEY: "secret",
+      },
+    });
+    const frontend = makeRuntimeConfig("frontend", {
+      cwd: "frontend",
+      start: "npm run web",
+      port: 3001,
+      baseUrl: "http://127.0.0.1:{port}",
+      readyUrl: "http://127.0.0.1:{port}",
+      env: {
+        NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+      },
+    });
+
+    const resolved = resolveWorkerRuntimeConfigs(frontend, [api, frontend], 2, "/tmp/w2");
+    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(
+      buildExecutionEnv(
+        {
+          workerId: 2,
+          testkit: {
+            serviceEnv: {
+              API_KEY: "secret",
+            },
+          },
+        },
+        {
+          DATABASE_URL: "gone",
+        },
+        {
+          PATH: "/usr/bin",
+        }
+      )
+    ).toEqual({
+      PATH: "/usr/bin",
+      API_KEY: "secret",
+      TESTKIT_ACTIVE: "1",
+      TESTKIT_WORKER_ID: "2",
+    });
+
+    expect(buildPlaywrightEnv({ workerId: 3, testkit: { serviceEnv: {} } }, "http://localhost:3000", {}))
+      .toMatchObject({
+        BASE_URL: "http://localhost:3000",
+        TESTKIT_WORKER_ID: "3",
+        PLAYWRIGHT_HTML_OPEN: "never",
+      });
+  });
+
+  it("parses runtime sockets", () => {
+    expect(numericPortFromUrl("http://localhost:3000")).toBe(3000);
+    expect(socketFromUrl("http://localhost:3000")).toEqual({
+      host: "127.0.0.1",
+      port: 3000,
+    });
+    expect(normalizeSocketHost("[::1]")).toBe("::1");
+  });
+});

package/lib/telemetry/index.mjs

@@ -0,0 +1,43 @@
+export async function uploadTelemetryArtifact(telemetry, artifact) {
+  if (!telemetry?.enabled) return { skipped: true, reason: "disabled" };
+  if (process.env.TESTKIT_TELEMETRY === "0") {
+    return { skipped: true, reason: "disabled-by-env" };
+  }
+  if (!telemetry.endpoint) {
+    return { skipped: true, reason: "missing-endpoint" };
+  }
+  if (!telemetry.tokenEnv) {
+    return { skipped: true, reason: "missing-token-env" };
+  }
+
+  const token = process.env[telemetry.tokenEnv];
+  if (!token) {
+    return { skipped: true, reason: "missing-token" };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), telemetry.timeoutMs || 3_000);
+
+  try {
+    const response = await fetch(telemetry.endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(artifact),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(
+        `telemetry upload failed with ${response.status}${body ? `: ${body.trim()}` : ""}`
+      );
+    }
+
+    return { skipped: false, ok: true };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/lib/timing/index.mjs

@@ -0,0 +1,73 @@
+import path from "path";
+
+export function createEmptyTimings() {
+  return {
+    version: 1,
+    files: {},
+  };
+}
+
+export function normalizeTimings(parsed) {
+  return {
+    version: 1,
+    files: parsed?.files && typeof parsed.files === "object" ? parsed.files : {},
+  };
+}
+
+export function applyTimingUpdates(timings, updates, updatedAt = new Date().toISOString()) {
+  const next = {
+    version: 1,
+    files: { ...timings.files },
+  };
+
+  for (const update of updates) {
+    const existing = next.files[update.key];
+    if (!existing) {
+      next.files[update.key] = {
+        durationMs: Math.max(1, Math.round(update.durationMs)),
+        runs: 1,
+        updatedAt,
+      };
+      continue;
+    }
+
+    const runs = Number(existing.runs || 0) + 1;
+    const durationMs = Math.max(
+      1,
+      Math.round(((existing.durationMs || update.durationMs) * (runs - 1) + update.durationMs) / runs)
+    );
+    next.files[update.key] = {
+      durationMs,
+      runs,
+      updatedAt,
+    };
+  }
+
+  return next;
+}
+
+export function estimateTaskDuration(timings, timingKey, suite) {
+  const cached = timings.files[timingKey];
+  if (cached?.durationMs) return cached.durationMs;
+
+  const base =
+    suite.framework === "playwright"
+      ? 20_000
+      : suite.type === "dal"
+        ? 4_000
+        : 8_000;
+  return Math.max(1_000, Math.round((base * suite.weight) / Math.max(1, suite.files.length)));
+}
+
+export function buildTimingKey(serviceName, suite, file) {
+  return [
+    serviceName,
+    suite.framework,
+    suite.type,
+    normalizePathSeparators(file),
+  ].join("|");
+}
+
+function normalizePathSeparators(filePath) {
+  return filePath.split(path.sep).join("/");
+}

package/lib/timing/index.test.mjs

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyTimingUpdates,
+  buildTimingKey,
+  createEmptyTimings,
+  estimateTaskDuration,
+  normalizeTimings,
+} from "./index.mjs";
+
+describe("timings", () => {
+  it("creates and normalizes empty timing structures", () => {
+    expect(createEmptyTimings()).toEqual({ version: 1, files: {} });
+    expect(normalizeTimings({})).toEqual({ version: 1, files: {} });
+  });
+
+  it("applies rolling timing updates", () => {
+    const next = applyTimingUpdates(
+      {
+        version: 1,
+        files: {
+          "api|k6|integration|a.js": {
+            durationMs: 1000,
+            runs: 1,
+            updatedAt: "2020-01-01T00:00:00.000Z",
+          },
+        },
+      },
+      [{ key: "api|k6|integration|a.js", durationMs: 3000 }],
+      "2020-01-02T00:00:00.000Z"
+    );
+
+    expect(next.files["api|k6|integration|a.js"]).toEqual({
+      durationMs: 2000,
+      runs: 2,
+      updatedAt: "2020-01-02T00:00:00.000Z",
+    });
+  });
+
+  it("estimates task durations and builds timing keys", () => {
+    expect(
+      estimateTaskDuration(
+        { files: { key: { durationMs: 3210 } } },
+        "key",
+        { framework: "k6", type: "integration", weight: 1, files: ["a.js"] }
+      )
+    ).toBe(3210);
+
+    expect(
+      estimateTaskDuration(
+        { files: {} },
+        "key",
+        { framework: "playwright", type: "e2e", weight: 2, files: ["a.js", "b.js"] }
+      )
+    ).toBe(20000);
+
+    expect(
+      buildTimingKey(
+        "api",
+        { framework: "k6", type: "integration" },
+        "tests/health.js"
+      )
+    ).toBe("api|k6|integration|tests/health.js");
+  });
+});

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "CLI for running manifest-defined local test suites across k6 and Playwright",
   "type": "module",
   "bin": {
     "testkit": "bin/testkit.mjs"
   },
+  "scripts": {
+    "test": "vitest run",
+    "test:unit": "vitest run lib",
+    "test:integration": "vitest run test/integration",
+    "test:system": "vitest run test/system --passWithNoTests"
+  },
   "files": [
     "bin/",
     "lib/",
-    "infra/neon-up.sh",
-    "infra/neon-down.sh",
     "vendor/"
   ],
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "vitest": "^3.2.4"
+  },
   "dependencies": {
     "cac": "^6.7.14",
     "execa": "^9.5.0"

package/infra/neon-down.sh

@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-# Deletes the ephemeral Neon branch from .state/
-# Requires: NEON_API_KEY, NEON_PROJECT_ID
-set -eo pipefail
-
-STATE_DIR="${STATE_DIR:-.state}"
-NEON_API="https://console.neon.tech/api/v2/projects/$NEON_PROJECT_ID"
-
-if [ ! -f "$STATE_DIR/neon_branch_id" ]; then
-  echo "No Neon branch to clean up"
-  exit 0
-fi
-
-BRANCH_ID=$(cat "$STATE_DIR/neon_branch_id")
-echo "Deleting Neon branch: $BRANCH_ID"
-curl -s -X DELETE "$NEON_API/branches/$BRANCH_ID" \
-  -H "Authorization: Bearer $NEON_API_KEY" > /dev/null
-echo "Neon branch deleted"