@elench/testkit 0.1.76 → 0.1.78

package/README.md

@@ -147,14 +147,11 @@ Create `testkit.config.ts` at repo root:
 
 ```ts
 import {
+  app,
+  database,
   defineConfig,
   defineFile,
-  nextApp,
-  nodeToolchain,
-  nodeApp,
-  seedCommand,
-  templateDatabase,
-  verifyModule,
+  toolchain,
 } from "@elench/testkit/config";
 
 export default defineConfig({
@@ -171,38 +168,41 @@ export default defineConfig({
     },
   },
   toolchains: {
-    frontendNode: nodeToolchain({
+    frontendNode: toolchain.node({
       cwd: "frontend",
       detect: "auto",
       install: "download",
     }),
   },
   services: {
-    api: nodeApp({
+    api: app.node({
       cwd: ".",
       entry: "src/index.ts",
       port: 3004,
       envFiles: [".env.testkit"],
-      database: templateDatabase({
-        inputs: ["db/schema.sql", "scripts/seed.ts"],
-        schema: "db/schema.sql",
-        seed: seedCommand("npm run db:seed"),
-        verify: verifyModule("src/testkit/verify-seed.ts#verifySeed"),
+      database: database.postgres({
+        template: {
+          inputs: ["db/schema.sql", "scripts/seed.ts"],
+          schema: "db/schema.sql",
+          seed: [{ kind: "command", run: "npm run db:seed" }],
+          verify: [{ kind: "module", target: "src/testkit/verify-seed.ts#verifySeed" }],
+        },
       }),
       runtime: {
         instances: 1,
         maxConcurrentTasks: 4,
       },
     }),
-    frontend: nextApp({
+    frontend: app.next({
       cwd: "frontend",
       mode: "start",
       port: 3000,
       dependsOn: ["api"],
       envFiles: ["frontend/.env.testkit"],
       env: {
-        NEXT_DIST_DIR: "{prepareDir}/dist",
-        NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+        values: {
+          NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+        },
       },
       runtime: {
         instances: 1,
@@ -258,17 +258,13 @@ state. It always executes in three explicit phases:
 - `seed`
 - `verify`
 
-For most repos, prefer the intent-focused helpers:
+For most repos, prefer declarative step objects directly inside
+`database.postgres({ template: ... })` and `runtime.prepare.steps`.
+The supported shapes are:
 
-- `schemaSql(...)`
-- `seedCommand(...)`
-- `seedModule(...)`
-- `verifyCommand(...)`
-- `verifyModule(...)`
-- `templateDatabase(...)`
-
-Use raw `commandStep(...)`, `sqlFileStep(...)`, and `moduleStep(...)` arrays when
-you need lower-level control over the exact stage layout.
+- `{ kind: "command", run: "..." }`
+- `{ kind: "sql-file", path: "..." }`
+- `{ kind: "module", target: "file.ts#exportName" }`
 
 `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
@@ -290,14 +286,14 @@ Example:
 
 ```ts
 toolchains: {
-  frontendNode: nodeToolchain({
+  frontendNode: toolchain.node({
     cwd: "frontend",
     detect: "auto",
     install: "download",
   }),
 },
 services: {
-  frontend: nextApp({
+  frontend: app.next({
     cwd: "frontend",
     port: 3000,
     runtime: {
@@ -369,8 +365,31 @@ Named HTTP profiles live in `testkit.config.ts` and can be referenced by name:
 
 ```ts
 import { defineHttpSuite } from "@elench/testkit";
+import { defineConfig, profiles } from "@elench/testkit/config";
+
+export default defineConfig({
+  profiles: {
+    http: {
+      defaultAuth: profiles.localJson({
+        password: "password",
+        identities: {
+          primary: {
+            email: "test@example.com",
+          },
+        },
+        session: {
+          authCookie: "session",
+        },
+        headers: {
+          contentTypeJson: true,
+          forwardedFor: "deterministic",
+        },
+      }).session(),
+    },
+  },
+});
 
-const suite = defineHttpSuite({ profile: "default-auth" }, ({ req, setupData }) => {
+const suite = defineHttpSuite({ profile: "defaultAuth" }, ({ req, setupData }) => {
   req("GET", "/api/auth/session", setupData);
 });
 ```
@@ -508,7 +527,7 @@ Git metadata.
 ## Local Databases
 
 `@elench/testkit` provisions Docker-managed local Postgres automatically for
-services that define `database: postgresDatabase(...)` or `database: templateDatabase(...)`.
+services that define `database: database.postgres(...)`.
 
 - template databases are cached
 - runtime databases are cloned from templates when binding is `per-runtime`

package/lib/app/doctor.mjs

@@ -4,6 +4,7 @@ import ts from "typescript";
 import { discoverTests } from "../discovery/index.mjs";
 import { loadConfigContext } from "../config/index.mjs";
 import { runTestkitTypecheck } from "./typecheck.mjs";
+import { findConfigFile } from "../config/config-loader.mjs";
 
 export async function runDoctor(options = {}) {
   const checks = [];
@@ -39,6 +40,17 @@ export async function runDoctor(options = {}) {
     details: playwrightViolations,
   });
 
+  const configImportViolations = findConfigImportViolations(productDir);
+  checks.push({
+    code: "config-import-hygiene",
+    level: configImportViolations.length === 0 ? "pass" : "fail",
+    message:
+      configImportViolations.length === 0
+        ? "Repo config does not import __testkit__ helper modules"
+        : `Found ${configImportViolations.length} repo config import violation(s)`,
+    details: configImportViolations,
+  });
+
   const hasBrowserOrNextWork = discovery.files.some((entry) => entry.selectionType === "pw");
   if (hasBrowserOrNextWork) {
     const nodeCount = discovery.coverageGraph?.nodes?.length || 0;
@@ -113,6 +125,31 @@ function findPlaywrightRuntimeImportViolations(productDir) {
   return violations;
 }
 
+function findConfigImportViolations(productDir) {
+  const configFile = findConfigFile(productDir);
+  if (!configFile || !fs.existsSync(configFile)) return [];
+
+  const sourceText = fs.readFileSync(configFile, "utf8");
+  const sourceFile = ts.createSourceFile(configFile, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const violations = [];
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const specifier = statement.moduleSpecifier.text;
+    if (!isRepoLocalConfigImportViolation(specifier)) continue;
+    const position = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
+    violations.push({
+      file: path.relative(productDir, configFile).split(path.sep).join("/"),
+      line: position.line + 1,
+      specifier,
+      snippet: statement.getText(sourceFile),
+    });
+  }
+
+  return violations;
+}
+
 function collectFiles(rootDir, out = []) {
   if (!fs.existsSync(rootDir)) return out;
   for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
@@ -129,6 +166,12 @@ function collectFiles(rootDir, out = []) {
   return out.sort((left, right) => left.localeCompare(right));
 }
 
+function isRepoLocalConfigImportViolation(specifier) {
+  if (typeof specifier !== "string") return false;
+  if (!specifier.startsWith(".") && !specifier.startsWith("/")) return false;
+  return specifier.includes("__testkit__");
+}
+
 function relativeViolation(productDir, absolutePath, sourceFile, statement) {
   const position = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
   return {

package/lib/config/runtime.test.mjs

@@ -19,7 +19,7 @@ describe("config runtime helpers", () => {
       normalizeRuntimePrepareConfig(
         {
           inputs: ["fixtures/users.json"],
-          steps: [{ kind: "module", specifier: "./scripts/setup.mjs#run", inputs: ["fixtures/users.json"] }],
+          steps: [{ kind: "module", target: "./scripts/setup.mjs#run", inputs: ["fixtures/users.json"] }],
         },
         "web"
       )
@@ -73,7 +73,7 @@ describe("config runtime helpers", () => {
 
   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/
+      /target must be a non-empty string/
     );
     expect(() => normalizeTemplateStepInputs([""], "runtime.prepare.steps[0]")).toThrow(
       /must be a non-empty string/

package/lib/config-api/index.d.ts

@@ -1,4 +1,4 @@
-import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
+import type { HttpSuiteConfig, RuntimeEnv, RuntimeOptions } from "../index";
 
 export interface DatabaseTemplateConfig {
   inputs?: string[];
@@ -22,7 +22,7 @@ export interface TemplateStepBaseConfig {
 
 export interface TemplateCommandStepConfig extends TemplateStepBaseConfig {
   kind: "command";
-  cmd: string;
+  run: string;
 }
 
 export interface TemplateSqlFileStepConfig extends TemplateStepBaseConfig {
@@ -32,7 +32,7 @@ export interface TemplateSqlFileStepConfig extends TemplateStepBaseConfig {
 
 export interface TemplateModuleStepConfig extends TemplateStepBaseConfig {
   kind: "module";
-  specifier: string;
+  target: string;
 }
 
 export type TemplateLifecycleStepConfig =
@@ -177,18 +177,209 @@ export interface ServiceConfig {
   skip?: SkipConfig;
 }
 
+export interface DatabaseBindingEnvConfig {
+  prefix: string;
+  service: string;
+}
+
+export interface PresetEnvConfig {
+  values?: Record<string, string>;
+  databases?: Record<string, DatabaseBindingEnvConfig>;
+}
+
 export interface TestkitFileMetadata {
   locks?: string[];
   skip?: string | { reason: string };
 }
 
-export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime"> {
+export interface ProfileRequestContext {
+  actor: string;
+  actorIndex: number;
+  env: RuntimeEnv;
+  phase: string;
+}
+
+export type ProfileValueFactory<TValue> =
+  | TValue
+  | ((context: ProfileRequestContext) => TValue);
+
+export interface ProfileRequestConfig {
+  body?: ProfileValueFactory<unknown>;
+  contentTypeJson?: boolean;
+  expect?: number | number[];
+  headers?: ProfileValueFactory<Record<string, string>>;
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+}
+
+export interface SessionAuthSourceConfig {
+  key: string;
+}
+
+export interface SessionAuthHeaderConfig {
+  header?: string;
+  prefix?: string;
+  source: SessionAuthSourceConfig;
+}
+
+export interface SessionCaptureConfig {
+  auth?: SessionAuthHeaderConfig;
+  cookies?: Record<string, string>;
+  fields?: Record<string, string>;
+}
+
+export interface SessionActorConfig {
+  bootstrap?: ProfileRequestConfig | ProfileRequestConfig[];
+  login: ProfileRequestConfig;
+  session: SessionCaptureConfig;
+}
+
+export interface ProfileHeaderContext<TSession = unknown> {
+  actor: string | null;
+  env: RuntimeEnv;
+  session: TSession | null;
+}
+
+export interface ProfileSessionHeaderConfig {
+  actor?: string;
+  field: string;
+  header: string;
+}
+
+export interface DeterministicForwardedForConfig {
+  actor?: string;
+  header?: string;
+  seed?: string;
+}
+
+export interface ProfileHeaderConfig<TSession = unknown> {
+  contentTypeJson?: boolean;
+  forwardedFor?: "deterministic" | DeterministicForwardedForConfig;
+  fromSession?: ProfileSessionHeaderConfig[];
+  values?: Record<string, string> | ((context: ProfileHeaderContext<TSession>) => Record<string, string>);
+}
+
+export interface RawHttpProfileOptions {
+  env?: RuntimeEnv;
+  headers?: ProfileHeaderConfig;
+  options?: RuntimeOptions;
+}
+
+export interface SessionHttpProfileOptions {
+  actor: SessionActorConfig;
+  env?: RuntimeEnv;
+  headers?: ProfileHeaderConfig<Record<string, unknown>>;
+  options?: RuntimeOptions;
+}
+
+export interface MultiActorHttpProfileOptions {
+  actors: Record<string, SessionActorConfig>;
+  env?: RuntimeEnv;
+  headers?: ProfileHeaderConfig<Record<string, Record<string, unknown>>>;
+  options?: RuntimeOptions;
+  primaryActor?: string;
+}
+
+export interface LocalJsonIdentityContext {
+  actor: string;
+}
+
+export type LocalJsonIdentityValue = string | ((context: LocalJsonIdentityContext) => string);
+
+export interface LocalJsonActorIdentityConfig {
+  email?: LocalJsonIdentityValue;
+  loginBody?: Record<string, unknown>;
+  name?: LocalJsonIdentityValue;
+  organizationName?: LocalJsonIdentityValue;
+  password?: LocalJsonIdentityValue;
+  signupBody?: Record<string, unknown>;
+}
+
+export interface LocalJsonSessionAuthOptions {
+  header?: string;
+  prefix?: string;
+  sourceKey?: string;
+}
+
+export interface LocalJsonSessionOptions {
+  auth?: LocalJsonSessionAuthOptions;
+  authCookie?: string;
+  cookies?: Record<string, string>;
+  fields?: Record<string, string>;
+  organizationIdPath?: string;
+  refreshCookie?: string;
+}
+
+export interface LocalJsonOrganizationHeaderConfig {
+  actor?: string;
+  field?: string;
+  header?: string;
+}
+
+export interface LocalJsonHeaderOptions {
+  contentTypeJson?: boolean;
+  forwardedFor?: "deterministic" | DeterministicForwardedForConfig;
+  organization?: false | string | LocalJsonOrganizationHeaderConfig;
+  values?: Record<string, string> | ((context: ProfileHeaderContext<unknown>) => Record<string, string>);
+}
+
+export interface LocalJsonSignupOptions {
+  enabled?: boolean;
+  expect?: number | number[];
+  path?: string;
+}
+
+export interface LocalJsonLoginOptions {
+  expect?: number | number[];
+  path?: string;
+}
+
+export interface LocalJsonProfileOptions {
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  identities?: Record<string, LocalJsonActorIdentityConfig>;
+  login?: LocalJsonLoginOptions;
+  options?: RuntimeOptions;
+  password?: LocalJsonIdentityValue;
+  session?: LocalJsonSessionOptions;
+  signup?: false | LocalJsonSignupOptions;
+}
+
+export interface LocalJsonSessionProfileOptions {
+  actor?: string;
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  identity?: LocalJsonActorIdentityConfig;
+  options?: RuntimeOptions;
+}
+
+export interface LocalJsonMultiActorProfileOptions {
+  actors?: string[] | Record<string, LocalJsonActorIdentityConfig>;
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  options?: RuntimeOptions;
+  primaryActor?: string;
+}
+
+export interface LocalJsonRawProfileOptions {
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  options?: RuntimeOptions;
+}
+
+export interface LocalJsonProfileBuilder {
+  multiActor(options?: LocalJsonMultiActorProfileOptions): HttpSuiteConfig<Record<string, Record<string, unknown>>>;
+  raw(options?: LocalJsonRawProfileOptions): HttpSuiteConfig<any>;
+  session(options?: LocalJsonSessionProfileOptions): HttpSuiteConfig<Record<string, unknown>>;
+}
+
+export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
   baseUrl?: string;
   build?: BuildConfig | null;
   buildInputs?: string[];
   cwd?: string;
   entry?: string;
-  env?: Record<string, string>;
+  env?: PresetEnvConfig;
   outDir?: string;
   port: number;
   readyPath?: string;
@@ -200,12 +391,12 @@ export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime">
   tsconfig?: string;
 }
 
-export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime"> {
+export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
   baseUrl?: string;
   build?: BuildConfig | null;
   buildInputs?: string[];
   cwd?: string;
-  env?: Record<string, string>;
+  env?: PresetEnvConfig;
   mode?: "dev" | "start";
   port: number;
   readyTimeoutMs?: number;
@@ -236,78 +427,35 @@ export interface TestkitConfig {
 }
 
 export declare function defineConfig<T extends TestkitConfig>(config: T): T;
-export declare function defineHttpProfile<T extends HttpSuiteConfig>(profile: T): T;
 export declare function defineFile<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">
-): TemplateCommandStepConfig;
-export declare function sqlFileStep(
-  filePath: string,
-  options?: Omit<TemplateSqlFileStepConfig, "kind" | "path">
-): TemplateSqlFileStepConfig;
-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 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 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<NextBuildConfig, "kind">): NextBuildConfig;
-export declare function nodeApp(options: NodeAppOptions): ServiceConfig;
-export declare function nextApp(options: NextAppOptions): ServiceConfig;
-export declare function clerkSessionProfile(options?: {
-  apiBase?: string;
-  needsAuth?: boolean;
-  secretKeyEnv?: string;
-}): HttpSuiteConfig;
-export declare function jsonSessionProfile(options?: {
-  body?: (context: { env: Record<string, string> }) => unknown;
-  cookieName?: string;
-  headers?: Record<string, string>;
-  loginPath?: string;
-  passwordEnv?: string;
-  successStatus?: number;
-  usernameEnv?: string;
-}): HttpSuiteConfig;
+export declare const app: {
+  node(options: NodeAppOptions): ServiceConfig;
+  next(options: NextAppOptions): ServiceConfig;
+};
+export declare const database: {
+  postgres(
+    options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      template?: DatabaseTemplateOptions;
+    }
+  ): LocalDatabaseConfig;
+  fixture(
+    options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      template?: DatabaseTemplateOptions;
+      discovery?: DiscoveryConfig;
+      envFiles?: string[];
+    }
+  ): ServiceConfig;
+};
+export declare const toolchain: {
+  node(options?: NodeToolchainConfig): NodeToolchainConfig;
+};
+export declare const profiles: {
+  custom<T extends HttpSuiteConfig>(profile: T): T;
+  localJson(options?: LocalJsonProfileOptions): LocalJsonProfileBuilder;
+  multiActor(options: MultiActorHttpProfileOptions): HttpSuiteConfig<Record<string, Record<string, unknown>>>;
+  raw(options?: RawHttpProfileOptions): HttpSuiteConfig<any>;
+  session(options: SessionHttpProfileOptions): HttpSuiteConfig<Record<string, unknown>>;
+};
 
 export declare function registerRepoConfig(config: unknown): void;
 export declare function getRepoConfig(): unknown;