@elench/testkit 0.1.59 → 0.1.61

package/lib/config/paths.mjs

@@ -0,0 +1,28 @@
+import fs from "fs";
+import path from "path";
+
+export function resolveServiceCwd(productDir, maybeRelative) {
+  return path.resolve(productDir, maybeRelative || ".");
+}
+
+export function ensureExistingPath(productDir, relativePath, label) {
+  const absolute = resolveServiceCwd(productDir, relativePath);
+  if (!fs.existsSync(absolute)) {
+    throw new Error(`${label} does not exist: ${relativePath}`);
+  }
+}
+
+export function normalizePath(value) {
+  return String(value || "")
+    .split(path.sep)
+    .join("/")
+    .replace(/^\.\/+/, "");
+}
+
+export function resolveProductDir(cwd, explicitDir) {
+  const dir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Product directory does not exist: ${dir}`);
+  }
+  return dir;
+}

package/lib/config/paths.test.mjs

@@ -0,0 +1,27 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { normalizePath, resolveProductDir, resolveServiceCwd } from "./paths.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("config path helpers", () => {
+  it("normalizes repo-relative paths consistently", () => {
+    expect(normalizePath("./src/app/page.tsx")).toBe("src/app/page.tsx");
+  });
+
+  it("resolves product and service directories", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-paths-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+
+    expect(resolveProductDir(productDir, ".")).toBe(productDir);
+    expect(resolveServiceCwd(productDir, "apps/web")).toBe(path.join(productDir, "apps", "web"));
+  });
+});

package/lib/config/runtime.mjs

@@ -0,0 +1,241 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_FILE_TIMEOUT_SECONDS, normalizeExecutionConfig, normalizeRuntimeMaxConcurrentTasks, normalizeRuntimeInstances } from "../runner/execution-config.mjs";
+import { normalizeKnownFailureIssueValidationConfig } from "../known-failures/github.mjs";
+import { normalizeRuntimeToolchain } from "../toolchains/index.mjs";
+import { resolveServiceCwd } from "./paths.mjs";
+
+export function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function normalizeReportingConfig(value) {
+  if (!value) return null;
+
+  const knownFailuresFile = normalizeOptionalString(value.knownFailuresFile);
+  if (!knownFailuresFile) {
+    throw new Error('testkit.setup.ts reporting.knownFailuresFile must be a non-empty string');
+  }
+
+  const issueValidation = normalizeKnownFailureIssueValidationConfig(value.issueValidation);
+
+  return {
+    knownFailuresFile,
+    issueValidation,
+  };
+}
+
+export function inferLocalRuntime(productDir, cwd) {
+  const absoluteCwd = resolveServiceCwd(productDir, cwd);
+  if (!fs.existsSync(absoluteCwd)) return undefined;
+
+  if (detectNextApp(absoluteCwd)) {
+    return {
+      cwd,
+      start: "./node_modules/.bin/next dev -p {port}",
+      port: 3000,
+      baseUrl: "http://127.0.0.1:{port}",
+      readyUrl: "http://127.0.0.1:{port}",
+      env: {},
+    };
+  }
+
+  if (fs.existsSync(path.join(absoluteCwd, "cmd", "server"))) {
+    return {
+      cwd,
+      start: "go run ./cmd/server",
+      port: 3000,
+      baseUrl: "http://127.0.0.1:{port}",
+      readyUrl: "http://127.0.0.1:{port}/health",
+      env: {},
+    };
+  }
+
+  if (fs.existsSync(path.join(absoluteCwd, "package.json")) && fs.existsSync(path.join(absoluteCwd, "src"))) {
+    return {
+      cwd,
+      start: "./node_modules/.bin/tsx watch src/index.ts",
+      port: 3000,
+      baseUrl: "http://127.0.0.1:{port}",
+      readyUrl: "http://127.0.0.1:{port}/health",
+      env: {},
+    };
+  }
+
+  return undefined;
+}
+
+export function normalizeRuntimeConfig(value, serviceName, toolchains) {
+  if (!value) {
+    return {
+      instances: 1,
+      maxConcurrentTasks: Number.POSITIVE_INFINITY,
+      prepare: {
+        inputs: [],
+        steps: [],
+      },
+      toolchain: null,
+    };
+  }
+
+  return {
+    instances: normalizeRuntimeInstances(value.instances ?? 1, `Service "${serviceName}" runtime.instances`),
+    maxConcurrentTasks: normalizeRuntimeMaxConcurrentTasks(
+      value.maxConcurrentTasks,
+      `Service "${serviceName}" runtime.maxConcurrentTasks`
+    ),
+    prepare: normalizeRuntimePrepareConfig(value.prepare, serviceName),
+    toolchain: normalizeRuntimeToolchain(
+      value.toolchain,
+      `Service "${serviceName}" runtime.toolchain`,
+      toolchains || {}
+    ),
+  };
+}
+
+export function normalizeRuntimePrepareConfig(value, serviceName) {
+  if (value == null) {
+    return {
+      inputs: [],
+      steps: [],
+    };
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error(`Service "${serviceName}" runtime.prepare must be an object`);
+  }
+
+  return {
+    inputs: normalizeTemplateInputs(value.inputs, `Service "${serviceName}" runtime.prepare`),
+    steps: normalizeTemplateLifecycleSteps(value.steps, `Service "${serviceName}" runtime.prepare.steps`),
+  };
+}
+
+export function normalizeTemplateInputs(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label}.inputs must be an array`);
+  }
+
+  return value.map((entry, index) => {
+    const normalized = normalizeOptionalString(entry);
+    if (!normalized) {
+      throw new Error(`${label}.inputs[${index}] must be a non-empty string`);
+    }
+    return normalized;
+  });
+}
+
+export function normalizeTemplateLifecycleSteps(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+
+  return value.map((step, index) => normalizeTemplateLifecycleStep(step, `${label}[${index}]`));
+}
+
+export function normalizeTemplateLifecycleStep(step, label) {
+  if (!step || typeof step !== "object") {
+    throw new Error(`${label} must be an object`);
+  }
+
+  const kind = normalizeOptionalString(step.kind);
+  if (kind === "command") {
+    const cmd = normalizeOptionalString(step.cmd);
+    if (!cmd) throw new Error(`${label}.cmd must be a non-empty string`);
+    return {
+      kind,
+      cmd,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeTemplateStepInputs(step.inputs, label),
+    };
+  }
+  if (kind === "sql-file") {
+    const filePath = normalizeOptionalString(step.path);
+    if (!filePath) throw new Error(`${label}.path must be a non-empty string`);
+    return {
+      kind,
+      path: filePath,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeTemplateStepInputs(step.inputs, label),
+    };
+  }
+  if (kind === "module") {
+    const specifier = normalizeOptionalString(step.specifier);
+    if (!specifier) throw new Error(`${label}.specifier must be a non-empty string`);
+    return {
+      kind,
+      specifier,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeTemplateStepInputs(step.inputs, label),
+    };
+  }
+
+  throw new Error(`${label}.kind must be one of: command, sql-file, module`);
+}
+
+export function normalizeTemplateStepInputs(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label}.inputs must be an array`);
+  }
+
+  return value.map((entry, index) => {
+    const normalized = normalizeOptionalString(entry);
+    if (!normalized) {
+      throw new Error(`${label}.inputs[${index}] must be a non-empty string`);
+    }
+    return normalized;
+  });
+}
+
+export function normalizeBrowserServiceConfig(value, serviceName) {
+  if (!value) return undefined;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Service "${serviceName}" browser config must be an object`);
+  }
+
+  const origins = Array.isArray(value.origins)
+    ? value.origins.map((origin) => normalizeOptionalString(origin)).filter(Boolean)
+    : [];
+
+  for (const origin of origins) {
+    try {
+      const parsed = new URL(origin);
+      if (!parsed.origin) throw new Error("missing origin");
+    } catch {
+      throw new Error(`Service "${serviceName}" browser.origins contains an invalid URL: ${origin}`);
+    }
+  }
+
+  if (origins.length === 0) return undefined;
+  return { origins };
+}
+
+export function normalizeRepoExecution(execution) {
+  if (!execution) {
+    return normalizeExecutionConfig({
+      workers: 1,
+      fileTimeoutSeconds: DEFAULT_FILE_TIMEOUT_SECONDS,
+    });
+  }
+  return normalizeExecutionConfig(execution);
+}
+
+export function detectNextApp(cwd) {
+  return (
+    fs.existsSync(path.join(cwd, "next.config.js")) ||
+    fs.existsSync(path.join(cwd, "next.config.mjs")) ||
+    fs.existsSync(path.join(cwd, "next.config.ts"))
+  );
+}
+
+export function parseModuleSpecifier(specifier) {
+  const [modulePath, exportName] = String(specifier).split("#", 2);
+  return {
+    modulePath,
+    exportName: exportName || "default",
+  };
+}

package/lib/config/runtime.test.mjs

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeBrowserServiceConfig,
+  normalizeRuntimePrepareConfig,
+  normalizeTemplateLifecycleStep,
+  normalizeTemplateStepInputs,
+  normalizeTemplateInputs,
+  parseModuleSpecifier,
+} from "./runtime.mjs";
+
+describe("config runtime helpers", () => {
+  it("normalizes template inputs and steps", () => {
+    expect(normalizeTemplateInputs(["foo.sql", "bar.sql"], "Service \"web\" database.template")).toEqual([
+      "foo.sql",
+      "bar.sql",
+    ]);
+    expect(
+      normalizeRuntimePrepareConfig(
+        {
+          inputs: ["fixtures/users.json"],
+          steps: [{ kind: "module", specifier: "./scripts/setup.mjs#run", inputs: ["fixtures/users.json"] }],
+        },
+        "web"
+      )
+    ).toEqual({
+      inputs: ["fixtures/users.json"],
+      steps: [
+        {
+          kind: "module",
+          specifier: "./scripts/setup.mjs#run",
+          cwd: null,
+          inputs: ["fixtures/users.json"],
+        },
+      ],
+    });
+  });
+
+  it("validates browser origins and module specifiers", () => {
+    expect(normalizeBrowserServiceConfig({ origins: ["http://localhost:3000"] }, "web")).toEqual({
+      origins: ["http://localhost:3000"],
+    });
+    expect(parseModuleSpecifier("./script.mjs#seed")).toEqual({
+      modulePath: "./script.mjs",
+      exportName: "seed",
+    });
+  });
+
+  it("rejects malformed lifecycle steps and empty step inputs", () => {
+    expect(() => normalizeTemplateLifecycleStep({ kind: "module" }, "runtime.prepare.steps[0]")).toThrow(
+      /specifier must be a non-empty string/
+    );
+    expect(() => normalizeTemplateStepInputs([""], "runtime.prepare.steps[0]")).toThrow(
+      /must be a non-empty string/
+    );
+  });
+});

package/lib/config/skip-config.mjs

@@ -0,0 +1,189 @@
+import { matchesSuiteSelectors, parseSuiteSelectors, suiteSelectionType } from "../runner/suite-selection.mjs";
+import { normalizePath } from "./paths.mjs";
+
+export function normalizeSkipReason(reason, label) {
+  const normalized = String(reason || "").trim();
+  if (!normalized) {
+    throw new Error(`${label} requires a non-empty reason`);
+  }
+  return normalized;
+}
+
+export function normalizeSkipConfig(value, { name, suites }) {
+  if (!value) return undefined;
+
+  const discoveredFiles = new Set();
+  const discoveredSuites = [];
+  for (const [type, typedSuites] of Object.entries(suites || {})) {
+    for (const suite of typedSuites || []) {
+      const displayType = suiteSelectionType(type, suite.framework || "k6");
+      discoveredSuites.push({ type, displayType, name: suite.name });
+      for (const file of suite.files || []) discoveredFiles.add(normalizePath(file));
+    }
+  }
+
+  const seenFiles = new Set();
+  const files = [];
+  for (const rule of value.files || []) {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" skip.files entries must be objects`);
+    }
+    const filePath = normalizePath(rule.path);
+    const reason = normalizeSkipReason(rule.reason, `Service "${name}" skip.files["${filePath}"]`);
+    if (!filePath) throw new Error(`Service "${name}" skip.files entries require a non-empty path`);
+    if (seenFiles.has(filePath)) {
+      throw new Error(`Service "${name}" defines duplicate skip.files path "${filePath}"`);
+    }
+    if (!discoveredFiles.has(filePath)) {
+      throw new Error(`Service "${name}" skip.files path "${filePath}" did not match any discovered suite file`);
+    }
+    seenFiles.add(filePath);
+    files.push({ path: filePath, reason });
+  }
+
+  const parsedSelectors = (value.suites || []).flatMap((rule, index) => {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" skip.suites entries must be objects`);
+    }
+    const selector = String(rule.selector || "").trim();
+    if (!selector) {
+      throw new Error(`Service "${name}" skip.suites[${index}] requires a non-empty selector`);
+    }
+    const reason = normalizeSkipReason(rule.reason, `Service "${name}" skip.suites["${selector}"]`);
+    const parsed = parseSuiteSelectors([selector]);
+    if (parsed.length !== 1) {
+      throw new Error(`Service "${name}" skip.suites["${selector}"] is invalid`);
+    }
+    return [{ selector: parsed[0], reason }];
+  });
+
+  const seenSelectors = new Set();
+  const suitesWithReasons = [];
+  for (const rule of parsedSelectors) {
+    if (seenSelectors.has(rule.selector.raw)) {
+      throw new Error(`Service "${name}" defines duplicate skip.suites selector "${rule.selector.raw}"`);
+    }
+    const matched = discoveredSuites.some((suite) =>
+      matchesSuiteSelectors(suite.displayType, suite.name, [rule.selector])
+    );
+    if (!matched) {
+      throw new Error(`Service "${name}" skip.suites selector "${rule.selector.raw}" did not match any discovered suite`);
+    }
+    seenSelectors.add(rule.selector.raw);
+    suitesWithReasons.push(rule);
+  }
+
+  if (files.length === 0 && suitesWithReasons.length === 0) return undefined;
+
+  return {
+    files,
+    fileReasonByPath: new Map(files.map((rule) => [rule.path, rule.reason])),
+    suites: suitesWithReasons,
+  };
+}
+
+export function normalizeServiceRequirements(value, { name, suites }) {
+  if (!value) return { suites: [], files: [], fileLocksByPath: new Map() };
+
+  const discoveredSuites = [];
+  const discoveredFiles = new Set();
+  for (const [type, typedSuites] of Object.entries(suites || {})) {
+    for (const suite of typedSuites || []) {
+      discoveredSuites.push({
+        displayType: suiteSelectionType(type, suite.framework || "k6"),
+        name: suite.name,
+      });
+      for (const file of suite.files || []) discoveredFiles.add(file);
+    }
+  }
+
+  const suiteRules = [];
+  const seenSelectors = new Set();
+  for (const rule of value.suites || []) {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" requirements.suites entries must be objects`);
+    }
+    const selector = String(rule.selector || "").trim();
+    if (!selector) {
+      throw new Error(`Service "${name}" requirements.suites entries require a selector`);
+    }
+    const parsed = parseSuiteSelectors([selector]);
+    if (parsed.length !== 1) {
+      throw new Error(`Service "${name}" requirements.suites["${selector}"] is invalid`);
+    }
+    const parsedSelector = parsed[0];
+    if (parsedSelector.kind !== "typed") {
+      throw new Error(
+        `Service "${name}" requirements.suites["${selector}"] must use a typed selector like int:health`
+      );
+    }
+    if (seenSelectors.has(parsedSelector.raw)) {
+      throw new Error(`Service "${name}" defines duplicate requirements.suites selector "${parsedSelector.raw}"`);
+    }
+    const matched = discoveredSuites.some((suite) =>
+      matchesSuiteSelectors(suite.displayType, suite.name, [parsedSelector])
+    );
+    if (!matched) {
+      throw new Error(
+        `Service "${name}" requirements.suites selector "${parsedSelector.raw}" did not match any discovered suite`
+      );
+    }
+    seenSelectors.add(parsedSelector.raw);
+    suiteRules.push({
+      selector: parsedSelector,
+      locks: normalizeRequirementLocks(
+        rule.locks,
+        `Service "${name}" requirements.suites["${parsedSelector.raw}"].locks`
+      ),
+    });
+  }
+
+  const fileRules = [];
+  const seenFiles = new Set();
+  for (const [index, rule] of (value.files || []).entries()) {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" requirements.files entries must be objects`);
+    }
+
+    const filePath = String(rule.path || "").trim();
+    if (!filePath) {
+      throw new Error(`Service "${name}" requirements.files[${index}] requires a path`);
+    }
+    if (!discoveredFiles.has(filePath)) {
+      throw new Error(`Service "${name}" requirements.files["${filePath}"] did not match any discovered test file`);
+    }
+    if (seenFiles.has(filePath)) {
+      throw new Error(`Service "${name}" defines duplicate requirements.files path "${filePath}"`);
+    }
+
+    seenFiles.add(filePath);
+    fileRules.push({
+      path: filePath,
+      locks: normalizeRequirementLocks(rule.locks, `Service "${name}" requirements.files["${filePath}"].locks`),
+    });
+  }
+
+  return {
+    suites: suiteRules,
+    files: fileRules,
+    fileLocksByPath: new Map(fileRules.map((rule) => [rule.path, rule.locks])),
+  };
+}
+
+export function normalizeRequirementLocks(value, label) {
+  const input = Array.isArray(value) ? value : value == null ? [] : [value];
+  const seen = new Set();
+  const locks = [];
+
+  for (const rawLock of input) {
+    const lockName = String(rawLock || "").trim();
+    if (!lockName) {
+      throw new Error(`${label} entries must be non-empty strings`);
+    }
+    if (seen.has(lockName)) continue;
+    seen.add(lockName);
+    locks.push(lockName);
+  }
+
+  return locks.sort();
+}

package/lib/config/skip-config.test.mjs

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeRequirementLocks,
+  normalizeServiceRequirements,
+  normalizeSkipConfig,
+  normalizeSkipReason,
+} from "./skip-config.mjs";
+
+const suites = {
+  integration: [
+    {
+      name: "health",
+      framework: "k6",
+      files: ["app/api/health/__testkit__/health.int.testkit.ts"],
+    },
+  ],
+  playwright: [
+    {
+      name: "campaigns",
+      framework: "playwright",
+      files: ["app/campaigns/__testkit__/campaigns.pw.testkit.ts"],
+    },
+  ],
+};
+
+describe("config skip helpers", () => {
+  it("normalizes skip reasons and requirement locks", () => {
+    expect(normalizeSkipReason("flaky on CI", "skip.files[0]")).toBe("flaky on CI");
+    expect(normalizeRequirementLocks(["db", "db", "redis"], "locks")).toEqual(["db", "redis"]);
+  });
+
+  it("normalizes skip config against discovered suites and files", () => {
+    const result = normalizeSkipConfig(
+      {
+        files: [{ path: "app/campaigns/__testkit__/campaigns.pw.testkit.ts", reason: "manual only" }],
+        suites: [{ selector: "pw:campaigns", reason: "broken locally" }],
+      },
+      { name: "web", suites }
+    );
+
+    expect(result.files).toHaveLength(1);
+    expect(result.suites).toHaveLength(1);
+  });
+
+  it("normalizes typed service requirements", () => {
+    const result = normalizeServiceRequirements(
+      {
+        suites: [{ selector: "int:health", locks: ["db"] }],
+        files: [{ path: "app/campaigns/__testkit__/campaigns.pw.testkit.ts", locks: ["browser", "browser"] }],
+      },
+      { name: "web", suites }
+    );
+
+    expect(result.suites[0]).toMatchObject({
+      selector: expect.objectContaining({ raw: "int:health" }),
+      locks: ["db"],
+    });
+    expect(result.files[0]).toMatchObject({
+      path: "app/campaigns/__testkit__/campaigns.pw.testkit.ts",
+      locks: ["browser"],
+    });
+  });
+});

package/lib/config/telemetry.mjs

@@ -0,0 +1,28 @@
+export function normalizeTelemetryConfig(telemetry) {
+  if (!telemetry) return null;
+  if (telemetry.endpoint) {
+    let parsed;
+    try {
+      parsed = new URL(telemetry.endpoint);
+    } catch {
+      throw new Error("testkit.setup telemetry.endpoint must be a valid URL");
+    }
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+      throw new Error("testkit.setup telemetry.endpoint must use http or https");
+    }
+  }
+  if (telemetry.enabled === true) {
+    if (!telemetry.endpoint) {
+      throw new Error("testkit.setup telemetry.endpoint is required when telemetry.enabled is true");
+    }
+    if (!telemetry.tokenEnv) {
+      throw new Error("testkit.setup telemetry.tokenEnv is required when telemetry.enabled is true");
+    }
+  }
+  return {
+    enabled: telemetry.enabled === true,
+    endpoint: telemetry.endpoint,
+    tokenEnv: telemetry.tokenEnv,
+    timeoutMs: telemetry.timeoutMs || 3000,
+  };
+}