@elench/testkit 0.1.66 → 0.1.67

package/lib/config/runtime.test.mjs

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   normalizeBrowserServiceConfig,
+  normalizeRuntimeConfig,
   normalizeRuntimePrepareConfig,
   normalizeTemplateLifecycleStep,
   normalizeTemplateStepInputs,
@@ -45,6 +46,31 @@ describe("config runtime helpers", () => {
     });
   });
 
+  it("folds declarative runtime.build into runtime.prepare", () => {
+    expect(
+      normalizeRuntimeConfig(
+        {
+          build: {
+            kind: "tsc",
+            entry: "src/server.ts",
+          },
+        },
+        "api",
+        {}
+      )
+    ).toMatchObject({
+      build: {
+        kind: "tsc",
+        entry: "src/server.ts",
+        tsconfig: "tsconfig.json",
+        outDir: "dist",
+      },
+      prepare: {
+        inputs: ["tsconfig.json", "package.json", "src"],
+      },
+    });
+  });
+
   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/

package/lib/coverage/index.test.mjs

@@ -19,13 +19,15 @@ describe("coverage graph builder", () => {
       productDir,
       "testkit.setup.ts",
       `
-        import { defineTestkitSetup, nextService } from "@elench/testkit/setup";
+        import { defineTestkitSetup, nextApp } from "@elench/testkit/setup";
 
         export default defineTestkitSetup({
           services: {
-            web: nextService({
+            web: nextApp({
               cwd: ".",
               start: "node server.js",
+              mode: "start",
+              build: null,
               baseUrl: "http://127.0.0.1:3000",
               readyUrl: "http://127.0.0.1:3000"
             })

package/lib/discovery/file-metadata.mjs

@@ -0,0 +1,122 @@
+import fs from "fs";
+import path from "path";
+import ts from "typescript";
+
+export function loadTestFileMetadataMap(productDir, suitesByService = {}) {
+  const metadataByPath = new Map();
+
+  for (const suites of Object.values(suitesByService || {})) {
+    for (const suiteList of Object.values(suites || {})) {
+      for (const suite of suiteList || []) {
+        for (const filePath of suite.files || []) {
+          if (metadataByPath.has(filePath)) continue;
+          metadataByPath.set(filePath, readTestFileMetadata(productDir, filePath));
+        }
+      }
+    }
+  }
+
+  return metadataByPath;
+}
+
+export function readTestFileMetadata(productDir, filePath) {
+  const absolutePath = path.join(productDir, filePath);
+  if (!fs.existsSync(absolutePath)) {
+    return emptyMetadata();
+  }
+
+  const sourceText = fs.readFileSync(absolutePath, "utf8");
+  const sourceFile = ts.createSourceFile(absolutePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement) || !hasExportModifier(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "testkit") continue;
+      const config = parseMetadataInitializer(declaration.initializer);
+      if (config) return config;
+    }
+  }
+
+  return emptyMetadata();
+}
+
+function parseMetadataInitializer(initializer) {
+  if (!initializer) return null;
+  if (ts.isCallExpression(initializer)) {
+    const callee = getCallIdentifier(initializer.expression);
+    if (callee === "defineTestkitFile" && initializer.arguments[0] && ts.isObjectLiteralExpression(initializer.arguments[0])) {
+      return parseMetadataObject(initializer.arguments[0]);
+    }
+    return null;
+  }
+  if (ts.isObjectLiteralExpression(initializer)) {
+    return parseMetadataObject(initializer);
+  }
+  return null;
+}
+
+function parseMetadataObject(node) {
+  const metadata = emptyMetadata();
+
+  for (const property of node.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const key = getPropertyName(property.name);
+    if (key === "locks") {
+      metadata.locks = parseLocks(property.initializer);
+      continue;
+    }
+    if (key === "skip") {
+      metadata.skipReason = parseSkipReason(property.initializer);
+    }
+  }
+
+  return metadata;
+}
+
+function parseLocks(node) {
+  if (!ts.isArrayLiteralExpression(node)) return [];
+  const values = [];
+  for (const entry of node.elements) {
+    const value = readStringLiteral(entry);
+    if (value) values.push(value);
+  }
+  return [...new Set(values)].sort();
+}
+
+function parseSkipReason(node) {
+  const literal = readStringLiteral(node);
+  if (literal) return literal;
+  if (!ts.isObjectLiteralExpression(node)) return null;
+  for (const property of node.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    if (getPropertyName(property.name) !== "reason") continue;
+    return readStringLiteral(property.initializer) || null;
+  }
+  return null;
+}
+
+function getCallIdentifier(node) {
+  if (ts.isIdentifier(node)) return node.text;
+  return null;
+}
+
+function getPropertyName(node) {
+  if (ts.isIdentifier(node) || ts.isStringLiteral(node)) return node.text;
+  return null;
+}
+
+function readStringLiteral(node) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return null;
+}
+
+function hasExportModifier(node) {
+  return (node.modifiers || []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+
+function emptyMetadata() {
+  return {
+    locks: [],
+    skipReason: null,
+  };
+}

package/lib/discovery/file-metadata.test.mjs

@@ -0,0 +1,51 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readTestFileMetadata } from "./file-metadata.mjs";
+
+const tempDirs = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("test file metadata", () => {
+  it("reads exported testkit metadata from object literals and helper calls", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-file-meta-"));
+    tempDirs.push(productDir);
+    fs.mkdirSync(path.join(productDir, "__testkit__"), { recursive: true });
+    fs.writeFileSync(
+      path.join(productDir, "__testkit__", "billing.int.testkit.ts"),
+      [
+        'import { defineTestkitFile } from "@elench/testkit/setup";',
+        'export const testkit = defineTestkitFile({',
+        '  skip: "Billing is stubbed locally",',
+        '  locks: ["background-workers", "background-workers"],',
+        "});",
+      ].join("\n")
+    );
+
+    expect(readTestFileMetadata(productDir, "__testkit__/billing.int.testkit.ts")).toEqual({
+      skipReason: "Billing is stubbed locally",
+      locks: ["background-workers"],
+    });
+  });
+
+  it("returns empty metadata when no export is present", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-file-meta-"));
+    tempDirs.push(productDir);
+    fs.mkdirSync(path.join(productDir, "__testkit__"), { recursive: true });
+    fs.writeFileSync(
+      path.join(productDir, "__testkit__", "health.int.testkit.ts"),
+      "export default {};\n"
+    );
+
+    expect(readTestFileMetadata(productDir, "__testkit__/health.int.testkit.ts")).toEqual({
+      skipReason: null,
+      locks: [],
+    });
+  });
+});

package/lib/discovery/index.mjs

@@ -207,8 +207,16 @@ function buildResolvedSuiteEntries(config, suite, internalType, filters) {
 
   for (const filePath of suite.files || []) {
     if (filters.fileNameSet.size > 0 && !filters.fileNameSet.has(filePath)) continue;
-    const fileLocks = config.testkit.requirements?.fileLocksByPath?.get(filePath) || [];
-    const skipReason = config.testkit.skip?.fileReasonByPath?.get(filePath) || suiteSkipReason || null;
+    const fileMetadata = config.testkit.fileMetadataByPath?.get(filePath) || { locks: [], skipReason: null };
+    const fileLocks = [
+      ...(config.testkit.requirements?.fileLocksByPath?.get(filePath) || []),
+      ...(fileMetadata.locks || []),
+    ];
+    const skipReason =
+      fileMetadata.skipReason ||
+      config.testkit.skip?.fileReasonByPath?.get(filePath) ||
+      suiteSkipReason ||
+      null;
     const skipped = Boolean(skipReason);
     if (filters.runnableOnly && skipped) continue;
     visibleFiles.push({

package/lib/discovery/index.test.mjs

@@ -30,14 +30,6 @@ describe("public discovery", () => {
                 start: "node server.js",
                 baseUrl: "http://127.0.0.1:3000",
                 readyUrl: "http://127.0.0.1:3000"
-              },
-              requirements: {
-                files: [
-                  {
-                    path: "src/api/routes/__testkit__/agent-configs-auth-gate.int.testkit.ts",
-                    locks: ["route-lock"]
-                  }
-                ]
               }
             },
             frontend: {
@@ -47,22 +39,30 @@ describe("public discovery", () => {
                 baseUrl: "http://127.0.0.1:3001",
                 readyUrl: "http://127.0.0.1:3001"
               },
-              dependsOn: ["api"],
-              skip: {
-                files: [
-                  {
-                    path: "frontend/src/app/login/__testkit__/auth.pw.testkit.ts",
-                    reason: "Auth is stubbed locally"
-                  }
-                ]
-              }
+              dependsOn: ["api"]
             }
           }
         });
       `
     );
-    writeFile(productDir, "src/api/routes/__testkit__/agent-configs-auth-gate.int.testkit.ts");
-    writeFile(productDir, "frontend/src/app/login/__testkit__/auth.pw.testkit.ts");
+    writeFile(
+      productDir,
+      "src/api/routes/__testkit__/agent-configs-auth-gate.int.testkit.ts",
+      [
+        'import { defineTestkitFile } from "@elench/testkit/setup";',
+        'export const testkit = defineTestkitFile({ locks: ["route-lock"] });',
+        "export {};",
+      ].join("\n")
+    );
+    writeFile(
+      productDir,
+      "frontend/src/app/login/__testkit__/auth.pw.testkit.ts",
+      [
+        'import { defineTestkitFile } from "@elench/testkit/setup";',
+        'export const testkit = defineTestkitFile({ skip: "Auth is stubbed locally" });',
+        "export {};",
+      ].join("\n")
+    );
 
     saveHistory(productDir, {
       version: 1,

package/lib/runner/planning.mjs

@@ -223,14 +223,15 @@ function applySkipRules(config, displayType, suiteName, files, opts = {}) {
     };
   }
   const skip = config.testkit?.skip;
-  if (!skip) {
+  const metadataByPath = config.testkit?.fileMetadataByPath || null;
+  if (!skip && !metadataByPath) {
     return {
       files,
       skippedFiles: [],
     };
   }
 
-  const matchingSuiteRules = skip.suites.filter((rule) =>
+  const matchingSuiteRules = (skip?.suites || []).filter((rule) =>
     matchesSuiteSelectors(displayType, suiteName, [rule.selector])
   );
   const suiteReason = matchingSuiteRules[0]?.reason || null;
@@ -239,7 +240,9 @@ function applySkipRules(config, displayType, suiteName, files, opts = {}) {
 
   for (const file of files) {
     const normalizedFile = normalizePathSeparators(file);
-    const reason = skip.fileReasonByPath.get(normalizedFile) || suiteReason;
+    const fileMetadata = config.testkit.fileMetadataByPath?.get(normalizedFile) || null;
+    const reason =
+      fileMetadata?.skipReason || skip?.fileReasonByPath?.get(normalizedFile) || suiteReason;
     if (reason) {
       skippedFiles.push({
         path: normalizedFile,
@@ -268,9 +271,13 @@ function resolveTaskLocks(config, suite, file) {
   }
 
   const normalizedFile = normalizePathSeparators(file);
+  const fileMetadata = config.testkit.fileMetadataByPath?.get(normalizedFile) || null;
   for (const lockName of config.testkit.requirements?.fileLocksByPath?.get(normalizedFile) || []) {
     locks.add(lockName);
   }
+  for (const lockName of fileMetadata?.locks || []) {
+    locks.add(lockName);
+  }
 
   return [...locks].sort();
 }

package/lib/runner/planning.test.mjs

@@ -138,6 +138,32 @@ describe("runner-planning", () => {
     ]);
   });
 
+  it("does not require repo-level skip config when file metadata is present", () => {
+    const config = makeConfig("api", {
+      suites: {
+        integration: [
+          {
+            name: "health",
+            files: ["__testkit__/health/health.int.testkit.ts"],
+          },
+        ],
+      },
+      testkit: {
+        fileMetadataByPath: new Map([
+          ["__testkit__/health/health.int.testkit.ts", { skipReason: null, locks: [] }],
+        ]),
+      },
+    });
+
+    expect(collectSuites(config, ["int"], [], [])).toEqual([
+      expect.objectContaining({
+        name: "health",
+        files: ["__testkit__/health/health.int.testkit.ts"],
+        skippedFiles: [],
+      }),
+    ]);
+  });
+
   it("applies lock requirements to matching suites and files", () => {
     const api = makeConfig("api", {
       suites: {

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;