@elench/testkit 0.1.117 → 0.1.119

package/lib/repo/state.mjs

@@ -0,0 +1,164 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+import { parseGitHubRepoSlug } from "../regressions/github.mjs";
+
+const IGNORED_DIRS = new Set([".git", ".testkit", "node_modules"]);
+
+export function collectRepoState(productDir) {
+  const repoRoot = readGit(productDir, ["rev-parse", "--show-toplevel"]);
+  if (!repoRoot) {
+    const fingerprint = fingerprintDirectory(productDir);
+    return {
+      kind: "nogit",
+      repoRoot: null,
+      worktreePath: path.resolve(productDir),
+      branch: null,
+      detached: false,
+      commitSha: null,
+      remoteUrl: null,
+      repoSlug: null,
+      dirty: false,
+      dirtyFingerprint: null,
+      contentFingerprint: fingerprint,
+      cacheKey: `nogit/${fingerprint}`,
+    };
+  }
+
+  const commitSha = readGit(productDir, ["rev-parse", "--verify", "HEAD"]);
+  const branchName = readGit(productDir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const remoteUrl = readGit(productDir, ["remote", "get-url", "origin"]);
+  const detached = branchName === "HEAD";
+  const dirtyFingerprint = fingerprintGitDirtyState(productDir);
+  const dirty = Boolean(dirtyFingerprint);
+  const baseCommit = commitSha || "unborn";
+
+  return {
+    kind: dirty ? "dirty" : "commit",
+    repoRoot,
+    worktreePath: path.resolve(repoRoot),
+    branch: detached ? null : branchName,
+    detached,
+    commitSha,
+    remoteUrl,
+    repoSlug: parseGitHubRepoSlug(remoteUrl),
+    dirty,
+    dirtyFingerprint,
+    contentFingerprint: null,
+    cacheKey: dirty
+      ? `dirty/${baseCommit}-${dirtyFingerprint}`
+      : `commits/${baseCommit}`,
+  };
+}
+
+export function summarizeRepoStateForMetadata(repoState) {
+  if (!repoState) return null;
+  return {
+    kind: repoState.kind,
+    cacheKey: repoState.cacheKey,
+    branch: repoState.branch,
+    detached: repoState.detached,
+    commitSha: repoState.commitSha,
+    dirty: repoState.dirty,
+    dirtyFingerprint: repoState.dirtyFingerprint,
+    contentFingerprint: repoState.contentFingerprint,
+    repoRoot: repoState.repoRoot,
+    worktreePath: repoState.worktreePath,
+    remoteUrl: repoState.remoteUrl,
+    repoSlug: repoState.repoSlug,
+  };
+}
+
+function fingerprintGitDirtyState(productDir) {
+  const hash = crypto.createHash("sha256");
+  let hasChanges = false;
+
+  const trackedStatus = readGit(productDir, ["status", "--porcelain=v1", "-uno"]) || "";
+  if (trackedStatus.trim()) {
+    hasChanges = true;
+    hash.update("tracked-status\0");
+    hash.update(trackedStatus);
+    appendGitOutput(hash, productDir, ["diff", "--binary", "--no-ext-diff"]);
+    appendGitOutput(hash, productDir, ["diff", "--binary", "--cached", "--no-ext-diff"]);
+  }
+
+  const untracked = readGit(productDir, ["ls-files", "--others", "--exclude-standard", "-z"]) || "";
+  const untrackedFiles = untracked
+    .split("\0")
+    .filter(Boolean)
+    .filter((entry) => !hasIgnoredPathSegment(entry))
+    .sort();
+  if (untrackedFiles.length > 0) {
+    hasChanges = true;
+    hash.update("untracked\0");
+    for (const relativePath of untrackedFiles) {
+      const absPath = path.join(productDir, relativePath);
+      if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) continue;
+      hash.update(`file:${normalizePath(relativePath)}\0`);
+      const stat = fs.statSync(absPath);
+      hash.update(`${stat.size}\0`);
+      hash.update(fs.readFileSync(absPath));
+    }
+  }
+
+  return hasChanges ? hash.digest("hex").slice(0, 24) : null;
+}
+
+function appendGitOutput(hash, cwd, args) {
+  const output = readGit(cwd, args) || "";
+  hash.update(args.join(" "));
+  hash.update("\0");
+  hash.update(output);
+  hash.update("\0");
+}
+
+function fingerprintDirectory(rootDir) {
+  const hash = crypto.createHash("sha256");
+  appendDirectoryToHash(hash, rootDir, rootDir);
+  return hash.digest("hex").slice(0, 24);
+}
+
+function appendDirectoryToHash(hash, rootDir, absPath) {
+  if (!fs.existsSync(absPath)) {
+    hash.update(`missing:${normalizePath(path.relative(rootDir, absPath))}`);
+    return;
+  }
+  const stat = fs.statSync(absPath);
+  if (stat.isDirectory()) {
+    const relative = path.relative(rootDir, absPath);
+    if (relative && hasIgnoredPathSegment(relative)) return;
+    hash.update(`dir:${normalizePath(relative)}`);
+    for (const entry of fs.readdirSync(absPath).sort()) {
+      if (IGNORED_DIRS.has(entry)) continue;
+      appendDirectoryToHash(hash, rootDir, path.join(absPath, entry));
+    }
+    return;
+  }
+  if (!stat.isFile()) return;
+  const relative = normalizePath(path.relative(rootDir, absPath));
+  hash.update(`file:${relative}:${stat.size}:${stat.mtimeMs}`);
+  hash.update(fs.readFileSync(absPath));
+}
+
+function hasIgnoredPathSegment(relativePath) {
+  return normalizePath(relativePath)
+    .split("/")
+    .some((segment) => IGNORED_DIRS.has(segment));
+}
+
+function normalizePath(value) {
+  return String(value).split(path.sep).join("/");
+}
+
+function readGit(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}

package/lib/runner/metadata.mjs

@@ -1,27 +1,22 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
-import { parseGitHubRepoSlug } from "../regressions/github.mjs";
+import { collectRepoState } from "../repo/state.mjs";
 
 export function collectGitMetadata(productDir) {
-  const read = (args) => {
-    try {
-      return execaSyncCompat("git", args, { cwd: productDir }).trim() || null;
-    } catch {
-      return null;
-    }
-  };
-
-  const remoteUrl = read(["remote", "get-url", "origin"]);
+  const state = collectRepoState(productDir);
 
   return {
-    branch: read(["rev-parse", "--abbrev-ref", "HEAD"]),
-    commitSha: read(["rev-parse", "HEAD"]),
-    repoRoot: read(["rev-parse", "--show-toplevel"]),
-    remoteUrl,
-    repoSlug: parseGitHubRepoSlug(remoteUrl),
+    branch: state.branch || (state.detached ? "HEAD" : null),
+    commitSha: state.commitSha,
+    repoRoot: state.repoRoot,
+    remoteUrl: state.remoteUrl,
+    repoSlug: state.repoSlug,
+    detached: state.detached,
+    dirty: state.dirty,
+    dirtyFingerprint: state.dirtyFingerprint,
+    worktreePath: state.worktreePath,
   };
 }
 
@@ -50,11 +45,3 @@ export function safeUsername() {
     return process.env.USER || process.env.USERNAME || null;
   }
 }
-
-function execaSyncCompat(command, args, options) {
-  return execFileSync(command, args, {
-    cwd: options?.cwd,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-}

package/lib/runner/template-steps.mjs

@@ -23,6 +23,12 @@ import {
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 const ROOT_ENTRY = path.join(PACKAGE_ROOT, "lib", "index.mjs");
 const CONFIG_ENTRY = path.join(PACKAGE_ROOT, "lib", "config-api", "index.mjs");
+const CONFIG_DATABASE_STEPS_ENTRY = path.join(
+  PACKAGE_ROOT,
+  "lib",
+  "config-api",
+  "database-steps.mjs"
+);
 const CONFIG_NEXT_TSCONFIG_ENTRY = path.join(
   PACKAGE_ROOT,
   "lib",
@@ -159,6 +165,7 @@ async function runConfiguredStep(config, step, env, resolvedToolchain, options =
     const bundledModule = await bundleConfiguredModule(config.productDir, step);
     const { exportName } = parseModuleSpecifier(step.specifier);
     const context = {
+      args: step.args ?? {},
       databaseUrl: runtimeEnv.DATABASE_URL || null,
       productDir: config.productDir,
       cwd,
@@ -267,6 +274,7 @@ function resolvePackageSubpath(specifier) {
   const subpath = specifier.slice("@elench/testkit".length);
   if (!subpath) return ROOT_ENTRY;
   if (subpath === "/config") return CONFIG_ENTRY;
+  if (subpath === "/config/database-steps") return CONFIG_DATABASE_STEPS_ENTRY;
   if (subpath === "/config/next-runtime-tsconfig") return CONFIG_NEXT_TSCONFIG_ENTRY;
   if (subpath === "/drizzle") return DRIZZLE_ENTRY;
   if (subpath === "/env") return ENV_ENTRY;

package/lib/runner/template.mjs

@@ -202,9 +202,6 @@ function finalizeSourceSchema(sourceSchema, context) {
   return {
     ...sourceSchema,
     ...(typeof sourceSchema.env === "string" ? { env: finalizeString(sourceSchema.env, context) } : {}),
-    ...(typeof sourceSchema.cachePath === "string"
-      ? { cachePath: finalizeString(sourceSchema.cachePath, context) }
-      : {}),
   };
 }
 

package/lib/runtime/index.d.ts

@@ -438,6 +438,41 @@ export declare function expectCondition(
   predicate: () => boolean,
   label: string
 ): boolean;
+export declare function expectRowCount<T>(
+  rows: T[],
+  expectedCount: number,
+  label?: string | null
+): boolean;
+export declare function expectSingleRow<T>(
+  rows: T[],
+  label?: string | null
+): T | null;
+export declare function expectNoRows<T>(
+  rows: T[],
+  label?: string | null
+): boolean;
+export declare function expectField<T extends Record<string, unknown>>(
+  row: T,
+  field: keyof T | string,
+  predicateOrExpected: unknown | ((value: unknown) => boolean),
+  label?: string | null
+): boolean;
+export declare function expectTruthyField<T extends Record<string, unknown>>(
+  row: T,
+  field: keyof T | string,
+  label?: string | null
+): boolean;
+export declare function expectType(
+  value: unknown,
+  typeName: "array" | "bigint" | "boolean" | "function" | "null" | "number" | "object" | "string" | "symbol" | "undefined",
+  label?: string | null
+): boolean;
+export declare function captureError(fn: () => unknown): unknown | null;
+export declare function expectError(
+  errorOrFn: unknown | (() => unknown) | null,
+  predicate?: ((error: unknown) => boolean) | null,
+  label?: string | null
+): boolean;
 
 export declare function runAuthGateChecks(
   rawReq: RawRequestClient,
@@ -458,17 +493,25 @@ export declare function runPaginationChecks(
 ): void;
 
 export interface RuntimeExpectNamespace {
+  captureError: typeof captureError;
   condition: typeof expectCondition;
   error: {
+    captured: typeof expectError;
     message: typeof expectErrorMessage;
     shape: typeof expectErrorShape;
   };
+  field: typeof expectField;
   json: typeof expectJson;
   jsonPath: typeof expectJsonPath;
+  noRows: typeof expectNoRows;
   notStatus: typeof expectNotStatus;
   response: typeof expectResponse;
+  rowCount: typeof expectRowCount;
+  singleRow: typeof expectSingleRow;
   status: typeof expectStatus;
   statusOneOf: typeof expectStatusOneOf;
+  truthyField: typeof expectTruthyField;
+  type: typeof expectType;
   value: typeof expectValue;
 }
 

package/lib/runtime/index.mjs

@@ -39,15 +39,23 @@ export {
   singleIterationOptions,
 } from "../runtime-src/k6/checks.js";
 export {
+  captureError,
   expectCondition,
+  expectError,
   expectErrorMessage,
   expectErrorShape,
+  expectField,
+  expectNoRows,
   expectJson,
   expectJsonPath,
   expectNotStatus,
   expectResponse,
+  expectRowCount,
+  expectSingleRow,
   expectStatus,
   expectStatusOneOf,
+  expectTruthyField,
+  expectType,
   expectValue,
 } from "../runtime-src/k6/http-assertions.js";
 export {
@@ -72,15 +80,23 @@ export {
 } from "../runtime-src/k6/http.js";
 
 import {
+  captureError,
   expectCondition,
+  expectError,
   expectErrorMessage,
   expectErrorShape,
+  expectField,
+  expectNoRows,
   expectJson,
   expectJsonPath,
   expectNotStatus,
   expectResponse,
+  expectRowCount,
+  expectSingleRow,
   expectStatus,
   expectStatusOneOf,
+  expectTruthyField,
+  expectType,
   expectValue,
 } from "../runtime-src/k6/http-assertions.js";
 import {
@@ -90,17 +106,25 @@ import {
 import { safeJson } from "../runtime-src/k6/http.js";
 
 export const expect = {
+  captureError,
   condition: expectCondition,
   error: {
+    captured: expectError,
     message: expectErrorMessage,
     shape: expectErrorShape,
   },
+  field: expectField,
   json: expectJson,
   jsonPath: expectJsonPath,
+  noRows: expectNoRows,
   notStatus: expectNotStatus,
   response: expectResponse,
+  rowCount: expectRowCount,
+  singleRow: expectSingleRow,
   status: expectStatus,
   statusOneOf: expectStatusOneOf,
+  truthyField: expectTruthyField,
+  type: expectType,
   value: expectValue,
 };
 

package/lib/runtime-src/k6/http-assertions.js

@@ -152,6 +152,77 @@ export function expectCondition(predicate, label) {
   });
 }
 
+export function expectRowCount(rows, expectedCount, label = null) {
+  const expected = Number(expectedCount);
+  if (!Number.isInteger(expected) || expected < 0) {
+    throw new Error("expectRowCount requires a non-negative integer count");
+  }
+  return expectValue(
+    rows,
+    (value) => Array.isArray(value) && value.length === expected,
+    normalizeLabel(label, `row count is ${expected}`)
+  );
+}
+
+export function expectSingleRow(rows, label = "query returns one row") {
+  if (!expectRowCount(rows, 1, label)) return null;
+  return rows[0];
+}
+
+export function expectNoRows(rows, label = "query returns no rows") {
+  return expectRowCount(rows, 0, label);
+}
+
+export function expectField(row, field, predicateOrExpected, label = null) {
+  const fieldName = String(field || "");
+  return expectValue(
+    row?.[fieldName],
+    normalizeFieldPredicate(predicateOrExpected),
+    normalizeLabel(label, `${fieldName || "field"} matches expectation`)
+  );
+}
+
+export function expectTruthyField(row, field, label = null) {
+  const fieldName = String(field || "");
+  return expectField(
+    row,
+    fieldName,
+    (value) => Boolean(value),
+    normalizeLabel(label, `${fieldName || "field"} is truthy`)
+  );
+}
+
+export function expectType(value, typeName, label = null) {
+  const expected = String(typeName || "").trim();
+  if (!expected) throw new Error("expectType requires a type name");
+  return expectValue(
+    value,
+    (actual) => actualType(actual) === expected,
+    normalizeLabel(label, `type is ${expected}`)
+  );
+}
+
+export function captureError(fn) {
+  try {
+    fn();
+    return null;
+  } catch (error) {
+    return error;
+  }
+}
+
+export function expectError(errorOrFn, predicate = null, label = null) {
+  const error = typeof errorOrFn === "function" ? captureError(errorOrFn) : errorOrFn;
+  return expectValue(
+    error,
+    (value) => {
+      if (!value) return false;
+      return typeof predicate === "function" ? Boolean(predicate(value)) : true;
+    },
+    normalizeLabel(label, "error is captured")
+  );
+}
+
 function buildHttpAssertionDetail({ kind, title, trace, expected, actual, response, message }) {
   return {
     kind,
@@ -238,6 +309,17 @@ function toValuePreview(value) {
   }
 }
 
+function normalizeFieldPredicate(predicateOrExpected) {
+  if (typeof predicateOrExpected === "function") return predicateOrExpected;
+  return (value) => Object.is(value, predicateOrExpected);
+}
+
+function actualType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
 function normalizeLabel(value, fallback) {
   const normalized = typeof value === "string" ? value.trim() : "";
   return normalized.length > 0 ? normalized : fallback;

package/lib/shared/configured-steps.mjs

@@ -55,31 +55,37 @@ export function normalizeConfiguredStep(step, label) {
   if (kind === "command") {
     const cmd = normalizeOptionalString(step.run);
     if (!cmd) throw new Error(`${label}.run must be a non-empty string`);
+    const args = normalizeStepArgs(step.args, label);
     return {
       kind,
       cmd,
       cwd: normalizeOptionalString(step.cwd),
       inputs: normalizeConfiguredStepInputs(step.inputs, label),
+      ...(args !== undefined ? { args } : {}),
     };
   }
   if (kind === "sql-file") {
     const filePath = normalizeOptionalString(step.path);
     if (!filePath) throw new Error(`${label}.path must be a non-empty string`);
+    const args = normalizeStepArgs(step.args, label);
     return {
       kind,
       path: filePath,
       cwd: normalizeOptionalString(step.cwd),
       inputs: normalizeConfiguredStepInputs(step.inputs, label),
+      ...(args !== undefined ? { args } : {}),
     };
   }
   if (kind === "module") {
     const specifier = normalizeOptionalString(step.target);
     if (!specifier) throw new Error(`${label}.target must be a non-empty string`);
+    const args = normalizeStepArgs(step.args, label);
     return {
       kind,
       specifier,
       cwd: normalizeOptionalString(step.cwd),
       inputs: normalizeConfiguredStepInputs(step.inputs, label),
+      ...(args !== undefined ? { args } : {}),
     };
   }
 
@@ -94,6 +100,15 @@ export function parseModuleSpecifier(specifier) {
   };
 }
 
+export function normalizeStepArgs(value, label) {
+  if (value == null) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    throw new Error(`${label}.args must be JSON-serializable`);
+  }
+}
+
 export function isBareModuleSpecifier(modulePath) {
   if (typeof modulePath !== "string" || modulePath.length === 0) return false;
   if (modulePath.startsWith("./") || modulePath.startsWith("../")) return false;
@@ -155,6 +170,7 @@ export function finalizeConfiguredStep(step, transform) {
     ...(typeof step.path === "string" ? { path: transform(step.path) } : {}),
     ...(typeof step.specifier === "string" ? { specifier: transform(step.specifier) } : {}),
     inputs: finalizeConfiguredInputs(step.inputs || [], transform),
+    ...(step.args !== undefined ? { args: step.args } : {}),
   };
 }
 

package/lib/ui/index.d.ts

@@ -1,3 +1,49 @@
 export * from "@playwright/test";
 export { defineConfig } from "../playwright/index";
 export type { PlaywrightConfigOptions } from "../playwright/index";
+
+export interface UiSandboxOptions {
+  allowRemote?: boolean;
+  backendBaseUrl?: string;
+  baseUrl?: string;
+  frontendBaseUrl?: string;
+  headers?: Record<string, string>;
+  prefix?: string;
+}
+
+export interface UiSandboxFixture {
+  id: string;
+  backendBaseUrl: string;
+  frontendBaseUrl: string;
+  page: import("@playwright/test").Page;
+}
+
+export declare function createUiSandbox(options?: UiSandboxOptions): {
+  expect: typeof import("@playwright/test").expect;
+  test: import("@playwright/test").TestType<
+    import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+      testkitSandbox: UiSandboxFixture;
+    },
+    import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions
+  >;
+};
+export declare function createSandboxId(options?: Pick<UiSandboxOptions, "prefix">): string;
+export declare function resolveFrontendBaseUrl(options?: UiSandboxOptions): string;
+export declare function resolveBackendBaseUrl(options?: UiSandboxOptions): string;
+export declare function assertSafeUiTarget(url: string, options?: Pick<UiSandboxOptions, "allowRemote">): string;
+export declare function assertSafeUiTargets(
+  urls?: string[],
+  options?: Pick<UiSandboxOptions, "allowRemote">
+): string[];
+export declare function createAuthedApiClient(
+  playwrightRequest?: typeof import("@playwright/test").request,
+  options?: UiSandboxOptions
+): Promise<import("@playwright/test").APIRequestContext>;
+export declare function waitForUiSettled(
+  page: import("@playwright/test").Page,
+  options?: { frames?: number; timeout?: number }
+): Promise<void>;
+export declare function waitForAnimationFrames(
+  page: import("@playwright/test").Page,
+  frames?: number
+): Promise<void>;

package/lib/ui/index.mjs

@@ -1,2 +1,13 @@
 export * from "@playwright/test";
 export { defineConfig } from "../playwright/index.mjs";
+export {
+  assertSafeUiTarget,
+  assertSafeUiTargets,
+  createAuthedApiClient,
+  createSandboxId,
+  createUiSandbox,
+  resolveBackendBaseUrl,
+  resolveFrontendBaseUrl,
+  waitForAnimationFrames,
+  waitForUiSettled,
+} from "./sandbox.mjs";