@elench/testkit 0.1.51 → 0.1.52

package/README.md

@@ -65,12 +65,14 @@ import {
   commandStep,
   defineTestkitSetup,
   localDatabase,
-  moduleStep,
   nextService,
   nodeToolchain,
+  schemaSql,
+  seedCommand,
+  seededDatabaseTemplate,
   service,
-  sqlFileStep,
   tsxService,
+  verifyModule,
 } from "@elench/testkit/setup";
 
 export default defineTestkitSetup({
@@ -103,12 +105,12 @@ export default defineTestkitSetup({
       }),
       envFiles: [".env.testkit"],
       database: localDatabase({
-        template: {
+        template: seededDatabaseTemplate({
           inputs: ["db/schema.sql", "scripts/seed.ts"],
-          migrate: [sqlFileStep("db/schema.sql")],
-          seed: [commandStep("npm run db:seed")],
-          verify: [moduleStep("src/testkit/verify-seed.ts#verifySeed")],
-        },
+          schema: schemaSql("db/schema.sql"),
+          seed: seedCommand("npm run db:seed"),
+          verify: verifyModule("src/testkit/verify-seed.ts#verifySeed"),
+        }),
       }),
       runtime: {
         instances: 1,
@@ -191,6 +193,25 @@ inputs, and writes cache state under the service runtime directory. This is the
 right way to move expensive browser targets from `next dev` / watch mode to
 stable build-and-start flows.
 
+`database.template` is the database-side equivalent for reusable template DB
+state. It always executes in three explicit phases:
+
+- `migrate`
+- `seed`
+- `verify`
+
+For most repos, prefer the intent-focused helpers:
+
+- `schemaSql(...)`
+- `seedCommand(...)`
+- `seedModule(...)`
+- `verifyCommand(...)`
+- `verifyModule(...)`
+- `seededDatabaseTemplate(...)`
+
+Use raw `commandStep(...)`, `sqlFileStep(...)`, and `moduleStep(...)` arrays when
+you need lower-level control over the exact stage layout.
+
 `runtime.toolchain` is the first-class way to make those prepare/start commands
 run under the correct Node toolchain instead of whatever `node`/`npm` happened
 to launch `testkit`. Node toolchains support:

package/lib/setup/index.d.ts

@@ -1,18 +1,18 @@
 import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
 
-export interface LocalDatabaseConfig {
-  provider: "local";
-  binding?: "shared" | "per-runtime";
-  image?: string;
-  password?: string;
-  reset?: boolean;
-  template?: {
-    inputs?: string[];
-    migrate?: TemplateLifecycleStepConfig[];
-    seed?: TemplateLifecycleStepConfig[];
-    verify?: TemplateLifecycleStepConfig[];
-  };
-  user?: string;
+export interface DatabaseTemplateConfig {
+  inputs?: string[];
+  migrate?: TemplateLifecycleStepConfig[];
+  seed?: TemplateLifecycleStepConfig[];
+  verify?: TemplateLifecycleStepConfig[];
+}
+
+export interface SeededDatabaseTemplateOptions {
+  inputs?: string[];
+  schema?: string | TemplateSqlFileStepConfig;
+  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
 }
 
 export interface TemplateStepBaseConfig {
@@ -40,6 +40,16 @@ export type TemplateLifecycleStepConfig =
   | TemplateSqlFileStepConfig
   | TemplateModuleStepConfig;
 
+export interface LocalDatabaseConfig {
+  provider: "local";
+  binding?: "shared" | "per-runtime";
+  image?: string;
+  password?: string;
+  reset?: boolean;
+  template?: DatabaseTemplateConfig;
+  user?: string;
+}
+
 export interface SkipFileRule {
   path: string;
   reason: string;
@@ -161,6 +171,29 @@ export declare function moduleStep(
   specifier: string,
   options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
 ): TemplateModuleStepConfig;
+export declare function schemaSql(
+  filePath: string,
+  options?: Omit<TemplateSqlFileStepConfig, "kind" | "path">
+): TemplateSqlFileStepConfig;
+export declare function seedCommand(
+  cmd: string,
+  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
+): TemplateCommandStepConfig;
+export declare function seedModule(
+  specifier: string,
+  options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
+): TemplateModuleStepConfig;
+export declare function verifyCommand(
+  cmd: string,
+  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
+): TemplateCommandStepConfig;
+export declare function verifyModule(
+  specifier: string,
+  options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
+): TemplateModuleStepConfig;
+export declare function seededDatabaseTemplate(
+  options?: SeededDatabaseTemplateOptions
+): DatabaseTemplateConfig;
 export declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
 export declare function goService(options: ServiceConfig["local"] & {
   command?: string;

package/lib/setup/index.mjs

@@ -56,6 +56,40 @@ export function moduleStep(specifier, options = {}) {
   };
 }
 
+export function schemaSql(filePath, options = {}) {
+  return sqlFileStep(filePath, options);
+}
+
+export function seedCommand(cmd, options = {}) {
+  return commandStep(cmd, options);
+}
+
+export function seedModule(specifier, options = {}) {
+  return moduleStep(specifier, options);
+}
+
+export function verifyCommand(cmd, options = {}) {
+  return commandStep(cmd, options);
+}
+
+export function verifyModule(specifier, options = {}) {
+  return moduleStep(specifier, options);
+}
+
+export function seededDatabaseTemplate(options = {}) {
+  const migrate = normalizeTemplateStepList(options.migrate);
+  const seed = normalizeTemplateStepList(options.seed);
+  const verify = normalizeTemplateStepList(options.verify);
+  const schema = normalizeSchemaStep(options.schema);
+
+  return {
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+    migrate: schema ? [schema, ...migrate] : migrate,
+    seed,
+    verify,
+  };
+}
+
 export function nodeToolchain(options = {}) {
   return {
     kind: "node",
@@ -218,6 +252,19 @@ function requiredNumber(value, label) {
   return value;
 }
 
+function normalizeTemplateStepList(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? [...value] : [value];
+}
+
+function normalizeSchemaStep(value) {
+  if (value == null) return null;
+  if (typeof value === "string") {
+    return sqlFileStep(value);
+  }
+  return value;
+}
+
 function envValue(name) {
   const env = getRuntimeEnv();
   const value = env?.rawEnv?.[name] || env?.[name];

package/lib/setup/index.test.mjs

@@ -1,5 +1,16 @@
 import { describe, expect, it } from "vitest";
-import { goService, nextService, nodeToolchain, tsxService } from "./index.mjs";
+import {
+  goService,
+  nextService,
+  nodeToolchain,
+  schemaSql,
+  seedCommand,
+  seedModule,
+  seededDatabaseTemplate,
+  tsxService,
+  verifyCommand,
+  verifyModule,
+} from "./index.mjs";
 
 describe("setup helpers", () => {
   it("emits plain next start commands without an exec prefix", () => {
@@ -31,4 +42,101 @@ describe("setup helpers", () => {
       install: "download",
     });
   });
+
+  it("emits semantic database template steps using the underlying step shapes", () => {
+    expect(schemaSql("db/schema.sql")).toEqual({
+      kind: "sql-file",
+      path: "db/schema.sql",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(seedCommand("npm run db:seed")).toEqual({
+      kind: "command",
+      cmd: "npm run db:seed",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(seedModule("scripts/seed.ts#seed")).toEqual({
+      kind: "module",
+      specifier: "scripts/seed.ts#seed",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(verifyCommand("npm run db:verify")).toEqual({
+      kind: "command",
+      cmd: "npm run db:verify",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(verifyModule("scripts/verify.ts#verify")).toEqual({
+      kind: "module",
+      specifier: "scripts/verify.ts#verify",
+      cwd: undefined,
+      inputs: undefined,
+    });
+  });
+
+  it("builds a seeded database template from schema, seed, and verify intents", () => {
+    expect(
+      seededDatabaseTemplate({
+        inputs: ["db/schema.sql", "scripts/seed.ts"],
+        schema: "db/schema.sql",
+        seed: seedCommand("npm run db:seed"),
+        verify: verifyModule("scripts/verify.ts#verifySeed"),
+      })
+    ).toEqual({
+      inputs: ["db/schema.sql", "scripts/seed.ts"],
+      migrate: [
+        {
+          kind: "sql-file",
+          path: "db/schema.sql",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+      seed: [
+        {
+          kind: "command",
+          cmd: "npm run db:seed",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+      verify: [
+        {
+          kind: "module",
+          specifier: "scripts/verify.ts#verifySeed",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+    });
+  });
+
+  it("prepends schema before explicit migrate steps and normalizes singletons to arrays", () => {
+    expect(
+      seededDatabaseTemplate({
+        schema: schemaSql("db/schema.sql", { cwd: "db" }),
+        migrate: seedCommand("echo migrate"),
+      })
+    ).toEqual({
+      inputs: undefined,
+      migrate: [
+        {
+          kind: "sql-file",
+          path: "db/schema.sql",
+          cwd: "db",
+          inputs: undefined,
+        },
+        {
+          kind: "command",
+          cmd: "echo migrate",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+      seed: [],
+      verify: [],
+    });
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",