@elench/testkit 0.1.17 → 0.1.19

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/runtime/index.mjs

@@ -0,0 +1,191 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const RUNNER_MANIFEST = "runner.manifest.json";
+const TESTKIT_CONFIG = "testkit.config.json";
+const DEFAULT_RUNTIME_DIR = path.join("tests", "_testkit");
+const METADATA_FILE = ".runtime-manifest.json";
+const RUNTIME_FORMAT = 1;
+
+export function installRuntime(options = {}) {
+  const productDir = resolveProductDir(process.cwd(), options.dir);
+  const runtimeDir = resolveRuntimeDir(productDir, options.path);
+  const sourceFiles = readBundledRuntimeFiles();
+
+  fs.mkdirSync(runtimeDir, { recursive: true });
+
+  for (const file of sourceFiles) {
+    const targetPath = path.join(runtimeDir, file.path);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, file.content);
+  }
+
+  const metadata = {
+    format: RUNTIME_FORMAT,
+    package: "@elench/testkit",
+    version: readPackageVersion(),
+    files: sourceFiles.map((file) => ({
+      path: file.path,
+      sha256: hashContent(file.content),
+    })),
+  };
+  fs.writeFileSync(
+    path.join(runtimeDir, METADATA_FILE),
+    `${JSON.stringify(metadata, null, 2)}\n`
+  );
+
+  return {
+    productDir,
+    runtimeDir,
+    relativeRuntimeDir: relativeToProduct(productDir, runtimeDir),
+    files: metadata.files,
+  };
+}
+
+export function getRuntimeStatus(options = {}) {
+  const productDir = resolveProductDir(process.cwd(), options.dir);
+  const runtimeDir = resolveRuntimeDir(productDir, options.path);
+  const sourceFiles = readBundledRuntimeFiles();
+  const metadataPath = path.join(runtimeDir, METADATA_FILE);
+
+  if (!fs.existsSync(runtimeDir) || !fs.existsSync(metadataPath)) {
+    return {
+      status: "missing",
+      productDir,
+      runtimeDir,
+      relativeRuntimeDir: relativeToProduct(productDir, runtimeDir),
+      missingFiles: sourceFiles.map((file) => file.path),
+      driftedFiles: [],
+    };
+  }
+
+  const missingFiles = [];
+  const driftedFiles = [];
+
+  for (const file of sourceFiles) {
+    const targetPath = path.join(runtimeDir, file.path);
+    if (!fs.existsSync(targetPath)) {
+      missingFiles.push(file.path);
+      continue;
+    }
+
+    const installed = fs.readFileSync(targetPath, "utf8");
+    if (installed !== file.content) {
+      driftedFiles.push(file.path);
+    }
+  }
+
+  const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+  const versionMatches = metadata.version === readPackageVersion();
+
+  return {
+    status:
+      missingFiles.length === 0 && driftedFiles.length === 0 && versionMatches
+        ? "installed"
+        : "drifted",
+    productDir,
+    runtimeDir,
+    relativeRuntimeDir: relativeToProduct(productDir, runtimeDir),
+    versionMatches,
+    missingFiles,
+    driftedFiles,
+  };
+}
+
+export function formatRuntimeStatus(result) {
+  if (result.status === "missing") {
+    return `Runtime not installed at ${result.relativeRuntimeDir}`;
+  }
+
+  if (result.status === "installed") {
+    return `Runtime at ${result.relativeRuntimeDir} is up to date`;
+  }
+
+  const problems = [];
+  if (result.missingFiles.length > 0) {
+    problems.push(`missing: ${result.missingFiles.join(", ")}`);
+  }
+  if (result.driftedFiles.length > 0) {
+    problems.push(`drifted: ${result.driftedFiles.join(", ")}`);
+  }
+  if (result.versionMatches === false) {
+    problems.push("version drift");
+  }
+
+  return `Runtime at ${result.relativeRuntimeDir} is drifted (${problems.join("; ")})`;
+}
+
+function resolveProductDir(cwd, explicitDir) {
+  const dir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
+  ensureProductFiles(dir);
+  return dir;
+}
+
+function ensureProductFiles(dir) {
+  const missing = [RUNNER_MANIFEST, TESTKIT_CONFIG].filter(
+    (file) => !fs.existsSync(path.join(dir, file))
+  );
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Expected ${missing.join(" and ")} in ${dir}. Either cd into a product directory or use --dir.`
+    );
+  }
+}
+
+function resolveRuntimeDir(productDir, explicitPath) {
+  return path.resolve(productDir, explicitPath || DEFAULT_RUNTIME_DIR);
+}
+
+function relativeToProduct(productDir, targetPath) {
+  return path.relative(productDir, targetPath) || ".";
+}
+
+function readBundledRuntimeFiles() {
+  const sourceDir = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "runtime-src"
+  );
+
+  return walkRuntimeFiles(sourceDir);
+}
+
+function walkRuntimeFiles(rootDir, relativeDir = "") {
+  const entries = fs.readdirSync(path.join(rootDir, relativeDir), {
+    withFileTypes: true,
+  });
+  const files = [];
+
+  for (const entry of entries) {
+    const nextRelative = path.join(relativeDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkRuntimeFiles(rootDir, nextRelative));
+      continue;
+    }
+
+    const absolute = path.join(rootDir, nextRelative);
+    files.push({
+      path: nextRelative.split(path.sep).join("/"),
+      content: fs.readFileSync(absolute, "utf8"),
+    });
+  }
+
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function readPackageVersion() {
+  const packagePath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "package.json"
+  );
+  return JSON.parse(fs.readFileSync(packagePath, "utf8")).version;
+}
+
+function hashContent(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}

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

@@ -0,0 +1,39 @@
+export function singleIterationOptions(overrides = {}) {
+  return {
+    iterations: 1,
+    thresholds: {
+      checks: ["rate==1.0"],
+      ...(overrides.thresholds || {}),
+    },
+    ...overrides,
+  };
+}
+
+export const defaultOptions = singleIterationOptions();
+
+export function json(res) {
+  return JSON.parse(res.body);
+}
+
+export function contains(rows, field, value) {
+  return rows.some((row) => row[field] === value);
+}
+
+export function allMatch(rows, predicate) {
+  return rows.length > 0 && rows.every(predicate);
+}
+
+export function isSorted(rows, field, direction = "asc") {
+  if (rows.length <= 1) return true;
+
+  for (let index = 1; index < rows.length; index += 1) {
+    if (direction === "asc" && rows[index][field] < rows[index - 1][field]) {
+      return false;
+    }
+    if (direction === "desc" && rows[index][field] > rows[index - 1][field]) {
+      return false;
+    }
+  }
+
+  return true;
+}