@elench/testkit 0.1.65 → 0.1.67

package/lib/runner/template-steps.mjs

@@ -4,7 +4,14 @@ import path from "path";
 import { build } from "esbuild";
 import { execa, execaCommand } from "execa";
 import { fileURLToPath } from "url";
-import { resolveServiceCwd } from "../config/index.mjs";
+import {
+  collectConfiguredInputs,
+  parseModuleSpecifier,
+  resolveConfiguredCwd,
+  resolveConfiguredPath,
+  summarizeConfiguredStep,
+} from "../shared/configured-steps.mjs";
+export { collectConfiguredInputs, parseModuleSpecifier, resolveConfiguredCwd, resolveConfiguredPath } from "../shared/configured-steps.mjs";
 import {
   announceResolvedToolchain,
   applyToolchainEnv,
@@ -72,35 +79,6 @@ export async function runConfiguredSteps({
   }
 }
 
-export function collectConfiguredInputs(productDir, { inputs = [], steps = [] } = {}) {
-  const collected = new Set();
-  for (const input of inputs) {
-    collected.add(resolveConfiguredPath(productDir, null, input));
-  }
-  for (const step of steps) {
-    if (step.kind === "sql-file") {
-      collected.add(resolveConfiguredPath(productDir, step.cwd, step.path));
-    }
-    if (step.kind === "module") {
-      collected.add(
-        resolveConfiguredPath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath)
-      );
-    }
-    for (const input of step.inputs || []) {
-      collected.add(resolveConfiguredPath(productDir, step.cwd, input));
-    }
-  }
-  return [...collected].sort();
-}
-
-export function resolveConfiguredCwd(productDir, stepCwd) {
-  return resolveServiceCwd(productDir, stepCwd || ".");
-}
-
-export function resolveConfiguredPath(productDir, stepCwd, targetPath) {
-  return path.resolve(resolveConfiguredCwd(productDir, stepCwd), targetPath);
-}
-
 async function runConfiguredStep(config, step, env, resolvedToolchain, options = {}) {
   const runtimeEnv = applyToolchainEnv(env, resolvedToolchain);
   const cwd = resolveConfiguredCwd(config.productDir, step.cwd);
@@ -253,21 +231,6 @@ function resolvePackageSubpath(specifier) {
   throw new Error(`Unsupported @elench/testkit import "${specifier}" while loading template step`);
 }
 
-function parseModuleSpecifier(specifier) {
-  const [modulePath, exportName] = String(specifier).split("#", 2);
-  return {
-    modulePath,
-    exportName: exportName || "default",
-  };
-}
-
-function summarizeConfiguredStep(step) {
-  if (step.kind === "command") return `command: ${String(step.cmd).trim()}`;
-  if (step.kind === "sql-file") return `sql: ${step.path}`;
-  if (step.kind === "module") return `module: ${step.specifier}`;
-  return step.kind;
-}
-
 async function awaitCapturedProcess(child, { livePrefix = "", liveWriter = null, logRecord = null } = {}) {
   const drains = [
     captureProcessOutput(child.stdout, "stdout", livePrefix, liveWriter, logRecord),

package/lib/runner/template.mjs

@@ -1,4 +1,5 @@
 import path from "path";
+import { finalizeConfiguredInputs, finalizeConfiguredSteps } from "../shared/configured-steps.mjs";
 import { readDatabaseInfo } from "./state-io.mjs";
 
 const PORT_STRIDE = 100;
@@ -183,22 +184,11 @@ function finalizeDatabaseTemplate(template, context) {
     };
   }
 
-  const finalizeStep = (step) => ({
-    ...step,
-    ...(typeof step.cmd === "string" ? { cmd: finalizeString(step.cmd, context) } : {}),
-    ...(typeof step.cwd === "string" ? { cwd: finalizeString(step.cwd, context) } : {}),
-    ...(typeof step.path === "string" ? { path: finalizeString(step.path, context) } : {}),
-    ...(typeof step.specifier === "string"
-      ? { specifier: finalizeString(step.specifier, context) }
-      : {}),
-    inputs: (step.inputs || []).map((input) => finalizeString(input, context)),
-  });
-
   return {
-    inputs: (template.inputs || []).map((input) => finalizeString(input, context)),
-    migrate: (template.migrate || []).map(finalizeStep),
-    seed: (template.seed || []).map(finalizeStep),
-    verify: (template.verify || []).map(finalizeStep),
+    inputs: finalizeConfiguredInputs(template.inputs || [], (value) => finalizeString(value, context)),
+    migrate: finalizeConfiguredSteps(template.migrate || [], (value) => finalizeString(value, context)),
+    seed: finalizeConfiguredSteps(template.seed || [], (value) => finalizeString(value, context)),
+    verify: finalizeConfiguredSteps(template.verify || [], (value) => finalizeString(value, context)),
   };
 }
 
@@ -356,20 +346,9 @@ function finalizeRuntimePrepare(prepare, context) {
     };
   }
 
-  const finalizeStep = (step) => ({
-    ...step,
-    ...(typeof step.cmd === "string" ? { cmd: finalizeString(step.cmd, context) } : {}),
-    ...(typeof step.cwd === "string" ? { cwd: finalizeString(step.cwd, context) } : {}),
-    ...(typeof step.path === "string" ? { path: finalizeString(step.path, context) } : {}),
-    ...(typeof step.specifier === "string"
-      ? { specifier: finalizeString(step.specifier, context) }
-      : {}),
-    inputs: (step.inputs || []).map((input) => finalizeString(input, context)),
-  });
-
   return {
-    inputs: (prepare.inputs || []).map((input) => finalizeString(input, context)),
-    steps: (prepare.steps || []).map(finalizeStep),
+    inputs: finalizeConfiguredInputs(prepare.inputs || [], (value) => finalizeString(value, context)),
+    steps: finalizeConfiguredSteps(prepare.steps || [], (value) => finalizeString(value, context)),
   };
 }
 

package/lib/setup/index.d.ts

@@ -7,7 +7,7 @@ export interface DatabaseTemplateConfig {
   verify?: TemplateLifecycleStepConfig[];
 }
 
-export interface SeededDatabaseTemplateOptions {
+export interface DatabaseTemplateOptions {
   inputs?: string[];
   schema?: string | TemplateSqlFileStepConfig;
   migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
@@ -40,6 +40,30 @@ export type TemplateLifecycleStepConfig =
   | TemplateSqlFileStepConfig
   | TemplateModuleStepConfig;
 
+export interface TscBuildConfig {
+  kind: "tsc";
+  cwd?: string;
+  entry?: string;
+  inputs?: string[];
+  outDir?: string;
+  tsconfig?: string;
+}
+
+export interface ScriptBuildConfig {
+  kind: "script";
+  cwd?: string;
+  inputs?: string[];
+  script: string;
+}
+
+export interface StepsBuildConfig {
+  kind: "steps";
+  inputs?: string[];
+  steps?: TemplateLifecycleStepConfig[];
+}
+
+export type BuildConfig = TscBuildConfig | ScriptBuildConfig | StepsBuildConfig;
+
 export interface LocalDatabaseConfig {
   provider: "local";
   binding?: "shared" | "per-runtime";
@@ -66,6 +90,7 @@ export interface SkipConfig {
 }
 
 export interface RuntimeConfig {
+  build?: BuildConfig | null;
   instances?: number;
   maxConcurrentTasks?: number;
   prepare?: {
@@ -126,7 +151,6 @@ export interface ServiceConfig {
   databaseFrom?: string;
   dependsOn?: string[];
   discovery?: DiscoveryConfig;
-  env?: Record<string, string>;
   envFile?: string;
   envFiles?: string[];
   browser?: BrowserServiceConfig;
@@ -144,6 +168,44 @@ export interface ServiceConfig {
   skip?: SkipConfig;
 }
 
+export interface TestkitFileMetadata {
+  locks?: string[];
+  skip?: string | { reason: string };
+}
+
+export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime"> {
+  baseUrl?: string;
+  build?: BuildConfig | null;
+  buildInputs?: string[];
+  cwd?: string;
+  entry?: string;
+  env?: Record<string, string>;
+  outDir?: string;
+  port: number;
+  readyPath?: string;
+  readyTimeoutMs?: number;
+  readyUrl?: string;
+  runtime?: Omit<RuntimeConfig, "build">;
+  start?: string;
+  toolchain?: string | NodeToolchainConfig;
+  tsconfig?: string;
+}
+
+export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime"> {
+  baseUrl?: string;
+  build?: BuildConfig | null;
+  buildInputs?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  mode?: "dev" | "start";
+  port: number;
+  readyTimeoutMs?: number;
+  readyUrl?: string;
+  runtime?: Omit<RuntimeConfig, "build">;
+  start?: string;
+  toolchain?: string | NodeToolchainConfig;
+}
+
 export interface TestkitSetup {
   discovery?: DiscoveryConfig;
   execution?: TestkitExecutionConfig;
@@ -166,8 +228,8 @@ export interface TestkitSetup {
 
 export declare function defineTestkitSetup<T extends TestkitSetup>(setup: T): T;
 export declare function defineHttpProfile<T extends HttpSuiteConfig>(profile: T): T;
-export declare function service<T extends ServiceConfig>(config: T): T;
-export declare function localDatabase(options?: Omit<LocalDatabaseConfig, "provider">): LocalDatabaseConfig;
+export declare function defineTestkitFile<T extends TestkitFileMetadata>(metadata: T): T;
+export declare function postgresDatabase(options?: Omit<LocalDatabaseConfig, "provider">): LocalDatabaseConfig;
 export declare function commandStep(
   cmd: string,
   options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
@@ -200,24 +262,29 @@ export declare function verifyModule(
   specifier: string,
   options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
 ): TemplateModuleStepConfig;
-export declare function seededDatabaseTemplate(
-  options?: SeededDatabaseTemplateOptions
-): DatabaseTemplateConfig;
+export declare function templateDatabase(
+  options?: DatabaseTemplateOptions & Omit<LocalDatabaseConfig, "provider" | "template">
+): LocalDatabaseConfig;
+export declare function postgresFixture(
+  options?: Omit<LocalDatabaseConfig, "provider"> & {
+    discovery?: DiscoveryConfig;
+    envFiles?: string[];
+  }
+): ServiceConfig;
+export declare function databaseServiceEnv(
+  prefix: string,
+  serviceName: string
+): Record<string, string>;
 export declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
-export declare function goService(options: ServiceConfig["local"] & {
-  command?: string;
-  entrypoint?: string;
-  envFiles?: string[];
-  readyPath?: string;
-}): ServiceConfig;
-export declare function nextService(options: ServiceConfig["local"] & {
-  envFiles?: string[];
-}): ServiceConfig;
-export declare function tsxService(options: ServiceConfig["local"] & {
-  entry?: string;
-  envFiles?: string[];
-  readyPath?: string;
-}): ServiceConfig;
+export declare function tscBuild(options?: Omit<TscBuildConfig, "kind">): TscBuildConfig;
+export declare function scriptBuild(
+  script: string,
+  options?: Omit<ScriptBuildConfig, "kind" | "script">
+): ScriptBuildConfig;
+export declare function stepsBuild(options?: Omit<StepsBuildConfig, "kind">): StepsBuildConfig;
+export declare function nextBuild(options?: Omit<ScriptBuildConfig, "kind" | "script">): ScriptBuildConfig;
+export declare function nodeApp(options: NodeAppOptions): ServiceConfig;
+export declare function nextApp(options: NextAppOptions): ServiceConfig;
 export declare function clerkSessionProfile(options?: {
   apiBase?: string;
   needsAuth?: boolean;

package/lib/setup/index.mjs

@@ -18,11 +18,11 @@ export function defineHttpProfile(profile) {
   return profile || {};
 }
 
-export function service(config) {
-  return config || {};
+export function defineTestkitFile(metadata) {
+  return metadata || {};
 }
 
-export function localDatabase(options = {}) {
+export function postgresDatabase(options = {}) {
   return {
     provider: "local",
     ...options,
@@ -76,7 +76,7 @@ export function verifyModule(specifier, options = {}) {
   return moduleStep(specifier, options);
 }
 
-export function seededDatabaseTemplate(options = {}) {
+function buildDatabaseTemplateConfig(options = {}) {
   const migrate = normalizeTemplateStepList(options.migrate);
   const seed = normalizeTemplateStepList(options.seed);
   const verify = normalizeTemplateStepList(options.verify);
@@ -90,6 +90,52 @@ export function seededDatabaseTemplate(options = {}) {
   };
 }
 
+export function templateDatabase(options = {}) {
+  const {
+    inputs,
+    schema,
+    migrate,
+    seed,
+    verify,
+    ...databaseOptions
+  } = options;
+  return postgresDatabase({
+    ...databaseOptions,
+    template: buildDatabaseTemplateConfig(options.template || { inputs, schema, migrate, seed, verify }),
+  });
+}
+
+export function postgresFixture(options = {}) {
+  const { discovery, envFiles, ...databaseOptions } = options;
+  return {
+    discovery: discovery || {
+      roots: [".testkit-fixture"],
+    },
+    envFiles,
+    local: false,
+    database: postgresDatabase(databaseOptions),
+  };
+}
+
+export function databaseServiceEnv(prefix, serviceName) {
+  const normalizedPrefix = String(prefix || "").trim().replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  if (!normalizedPrefix) {
+    throw new Error("databaseServiceEnv prefix must be a non-empty string");
+  }
+  if (!serviceName || !String(serviceName).trim()) {
+    throw new Error("databaseServiceEnv serviceName must be a non-empty string");
+  }
+
+  return {
+    [`${normalizedPrefix}_DATABASE_HOST`]: `{dbHost:${serviceName}}`,
+    [`${normalizedPrefix}_DATABASE_PORT`]: `{dbPort:${serviceName}}`,
+    [`${normalizedPrefix}_DATABASE_NAME`]: `{dbName:${serviceName}}`,
+    [`${normalizedPrefix}_DATABASE_USER`]: `{dbUser:${serviceName}}`,
+    [`${normalizedPrefix}_DATABASE_PASSWORD`]: `{dbPassword:${serviceName}}`,
+    [`${normalizedPrefix}_DATABASE_SSL`]: "0",
+  };
+}
+
 export function nodeToolchain(options = {}) {
   return {
     kind: "node",
@@ -97,61 +143,137 @@ export function nodeToolchain(options = {}) {
   };
 }
 
-export function goService(options = {}) {
-  const cwd = options.cwd || ".";
-  const port = requiredNumber(options.port, "goService port");
-  const readyPath = options.readyPath || "/health";
-  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+export function tscBuild(options = {}) {
+  return {
+    kind: "tsc",
+    cwd: options.cwd,
+    entry: options.entry || "src/index.ts",
+    tsconfig: options.tsconfig || "tsconfig.json",
+    outDir: options.outDir || "dist",
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+  };
+}
 
+export function scriptBuild(script, options = {}) {
   return {
-    ...service(options),
-    local: {
-      cwd,
-      start: options.start || defaultGoStartCommand(options),
-      port,
-      baseUrl,
-      readyUrl: options.readyUrl || `${baseUrl}${readyPath}`,
-      readyTimeoutMs: options.readyTimeoutMs,
-      env: options.env || {},
-    },
+    kind: "script",
+    script,
+    cwd: options.cwd,
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+  };
+}
+
+export function stepsBuild(options = {}) {
+  return {
+    kind: "steps",
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+    steps: Array.isArray(options.steps) ? [...options.steps] : [],
   };
 }
 
-export function nextService(options = {}) {
-  const cwd = options.cwd || ".";
-  const port = requiredNumber(options.port, "nextService port");
-  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
+export function nextBuild(options = {}) {
+  return scriptBuild("./node_modules/.bin/next build", options);
+}
+
+export function nodeApp(options = {}) {
+  const {
+    baseUrl: explicitBaseUrl,
+    build: explicitBuild,
+    buildInputs,
+    cwd = ".",
+    entry = "src/index.ts",
+    env = {},
+    envFiles,
+    outDir = "dist",
+    port,
+    readyPath = "/health",
+    readyTimeoutMs,
+    readyUrl: explicitReadyUrl,
+    runtime,
+    start: explicitStart,
+    toolchain,
+    tsconfig = "tsconfig.json",
+    ...serviceConfig
+  } = options;
+
+  const normalizedPort = requiredNumber(port, "nodeApp port");
+  const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
+  const build = explicitBuild === undefined ? tscBuild({
+    cwd,
+    entry,
+    tsconfig,
+    outDir,
+    inputs: buildInputs,
+  }) : explicitBuild;
+  const start = explicitStart || resolveNodeAppStart(build, entry);
 
   return {
-    ...service(options),
+    ...serviceConfig,
+    envFiles,
+    runtime: {
+      ...(runtime || {}),
+      build,
+      toolchain: toolchain ?? runtime?.toolchain,
+    },
     local: {
       cwd,
-      start: options.start || "./node_modules/.bin/next dev -p {port}",
-      port,
+      start,
+      port: normalizedPort,
       baseUrl,
-      readyUrl: options.readyUrl || baseUrl,
-      readyTimeoutMs: options.readyTimeoutMs,
-      env: options.env || {},
+      readyUrl: explicitReadyUrl || `${baseUrl}${readyPath}`,
+      readyTimeoutMs,
+      env,
     },
   };
 }
 
-export function tsxService(options = {}) {
-  const cwd = options.cwd || ".";
-  const port = requiredNumber(options.port, "tsxService port");
-  const baseUrl = options.baseUrl || "http://127.0.0.1:{port}";
-  const entry = options.entry || "src/index.ts";
+export function nextApp(options = {}) {
+  const {
+    baseUrl: explicitBaseUrl,
+    browser,
+    build: explicitBuild,
+    buildInputs,
+    cwd = ".",
+    dependsOn,
+    env = {},
+    envFiles,
+    mode = "dev",
+    port,
+    readyTimeoutMs,
+    readyUrl: explicitReadyUrl,
+    runtime,
+    start: explicitStart,
+    toolchain,
+    ...serviceConfig
+  } = options;
+
+  const normalizedPort = requiredNumber(port, "nextApp port");
+  const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
+  const build = mode === "start" ? explicitBuild || nextBuild({ cwd, inputs: buildInputs }) : explicitBuild || null;
+  const start =
+    explicitStart ||
+    (mode === "start"
+      ? "./node_modules/.bin/next start --port {port}"
+      : "./node_modules/.bin/next dev -p {port}");
 
   return {
-    ...service(options),
+    ...serviceConfig,
+    envFiles,
+    dependsOn: Array.isArray(dependsOn) ? [...dependsOn] : dependsOn,
+    browser,
+    runtime: {
+      ...(runtime || {}),
+      build,
+      toolchain: toolchain ?? runtime?.toolchain,
+    },
     local: {
       cwd,
-      start: options.start || `./node_modules/.bin/tsx watch ${entry}`,
-      port,
+      start,
+      port: normalizedPort,
       baseUrl,
-      readyUrl: options.readyUrl || `${baseUrl}${options.readyPath || "/health"}`,
-      readyTimeoutMs: options.readyTimeoutMs,
-      env: options.env || {},
+      readyUrl: explicitReadyUrl || baseUrl,
+      readyTimeoutMs,
+      env,
     },
   };
 }
@@ -235,16 +357,6 @@ export {
   runtimeJson,
 };
 
-function defaultGoStartCommand(options) {
-  if (options.command) {
-    return `go run ${options.command}`;
-  }
-  if (options.entrypoint) {
-    return `go run ${options.entrypoint}`;
-  }
-  return "go run ./cmd/server";
-}
-
 function requiredNumber(value, label) {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`${label} must be a positive integer`);
@@ -252,6 +364,14 @@ function requiredNumber(value, label) {
   return value;
 }
 
+function resolveNodeAppStart(build, entry) {
+  if (build?.kind === "tsc") {
+    const compiled = compiledEntryFromSource(entry || build.entry || "src/index.ts", build.outDir || "dist");
+    return `node {prepareDir}/${compiled}`;
+  }
+  return `./node_modules/.bin/tsx ${entry || "src/index.ts"}`;
+}
+
 function normalizeTemplateStepList(value) {
   if (value == null) return [];
   return Array.isArray(value) ? [...value] : [value];
@@ -265,6 +385,13 @@ function normalizeSchemaStep(value) {
   return value;
 }
 
+function compiledEntryFromSource(entry, outDir) {
+  const normalized = String(entry || "src/index.ts").replaceAll("\\", "/");
+  const compiled = normalized.replace(/\.[cm]?[jt]sx?$/i, ".js");
+  const relative = compiled.startsWith("src/") ? compiled.slice(4) : compiled;
+  return `${outDir}/${relative}`.replace(/\/+/g, "/");
+}
+
 function envValue(name) {
   const env = getRuntimeEnv();
   const value = env?.rawEnv?.[name] || env?.[name];