@elench/testkit 0.1.132 → 0.1.134

package/lib/cli/commands/guard/unsafe-entrypoint.mjs

@@ -0,0 +1,27 @@
+import { Command, Flags } from "@oclif/core";
+
+export default class GuardUnsafeEntrypointCommand extends Command {
+  static summary = "Fail a local script that must be run through Testkit";
+
+  static flags = {
+    command: Flags.string({
+      char: "c",
+      description: "Disabled command name shown in the error message",
+      required: true,
+    }),
+    use: Flags.string({
+      char: "u",
+      description: "Replacement command shown in the error message",
+      required: true,
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(GuardUnsafeEntrypointCommand);
+    this.error(
+      `${flags.command} is disabled because DB-touching tests must run through the isolated testkit harness.\n` +
+        `Use ${flags.use} instead.`,
+      { exit: 1 }
+    );
+  }
+}

package/lib/cli/entrypoint.mjs

@@ -16,6 +16,7 @@ export function normalizeCliArgs(argv) {
     "lint",
     "browser",
     "db",
+    "guard",
   ]);
   const runTypeShortcuts = new Set(publicTestTypeList({ includeAll: true }));
   const valueFlags = new Set([
@@ -40,6 +41,8 @@ export function normalizeCliArgs(argv) {
     "--provider-arg",
     "--message",
     "--prompt",
+    "--command",
+    "--use",
   ]);
   const positionals = findPositionals(argv, valueFlags);
   const firstPositional = positionals[0] || null;

package/lib/env/index.d.ts

@@ -6,6 +6,29 @@ export interface LoadDotenvFilesOptions {
   override?: boolean;
 }
 
+export interface PostgresConnectionEnvFallback {
+  database?: string;
+  host?: string;
+  password?: string;
+  port?: number | string;
+  ssl?: boolean;
+  username?: string;
+}
+
+export interface PostgresConnectionEnvOptions {
+  env?: NodeJS.ProcessEnv;
+  fallback?: PostgresConnectionEnvFallback;
+}
+
+export interface PostgresConnectionEnvValue {
+  database: string;
+  host: string;
+  password: string;
+  port: number;
+  ssl: boolean;
+  username: string;
+}
+
 export declare function isManagedRuntime(env?: NodeJS.ProcessEnv): boolean;
 export declare function shouldLoadDotenv(env?: NodeJS.ProcessEnv): boolean;
 export declare function loadDotenvFiles(options?: LoadDotenvFilesOptions): {
@@ -15,3 +38,7 @@ export declare function assertLocalDatabaseUrl(
   env?: NodeJS.ProcessEnv,
   consumer?: string
 ): void;
+export declare function readPostgresConnectionFromEnv(
+  prefix: string,
+  options?: PostgresConnectionEnvOptions
+): PostgresConnectionEnvValue;

package/lib/env/index.mjs

@@ -63,3 +63,57 @@ export function assertLocalDatabaseUrl(env = process.env, consumer = "This comma
     );
   }
 }
+
+export function readPostgresConnectionFromEnv(prefix, options = {}) {
+  const env = options.env || process.env;
+  const normalizedPrefix = String(prefix || "").trim();
+  if (!normalizedPrefix) {
+    throw new Error("readPostgresConnectionFromEnv requires an environment variable prefix");
+  }
+
+  const fallback = options.fallback || {};
+  return {
+    host: readEnvValue(env, `${normalizedPrefix}_HOST`, fallback.host),
+    port: readEnvPort(env, `${normalizedPrefix}_PORT`, fallback.port),
+    database: readEnvValue(env, `${normalizedPrefix}_NAME`, fallback.database),
+    username: readEnvValue(env, `${normalizedPrefix}_USER`, fallback.username),
+    password: readEnvValue(env, `${normalizedPrefix}_PASSWORD`, fallback.password),
+    ssl: readEnvBoolean(env, `${normalizedPrefix}_SSL`, fallback.ssl ?? false),
+  };
+}
+
+function readEnvValue(env, name, fallback) {
+  const value = env?.[name]?.trim();
+  if (value) return value;
+  if (fallback != null && String(fallback).trim()) return String(fallback).trim();
+  throw new Error(`${name} environment variable is required`);
+}
+
+function readEnvPort(env, name, fallback) {
+  const raw = env?.[name]?.trim();
+  const value = raw || (fallback == null ? "" : String(fallback));
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function readEnvBoolean(env, name, fallback) {
+  const value = env?.[name];
+  if (!value) return Boolean(fallback);
+  switch (value.trim().toLowerCase()) {
+    case "1":
+    case "true":
+    case "yes":
+    case "on":
+      return true;
+    case "0":
+    case "false":
+    case "no":
+    case "off":
+      return false;
+    default:
+      return Boolean(fallback);
+  }
+}

package/lib/runtime/index.d.ts

@@ -432,11 +432,23 @@ export declare function expectResponse(
 export declare function expectValue<T>(
   value: T,
   predicate: (value: T) => boolean,
-  label: string
+  label: string,
+  options?: {
+    actual?: ((value: T) => unknown) | unknown;
+    describeFailure?: ((value: T) => string) | string;
+    expected?: unknown;
+    kind?: string;
+  }
 ): boolean;
 export declare function expectCondition(
   predicate: () => boolean,
-  label: string
+  label: string,
+  options?: {
+    actual?: (() => unknown) | unknown;
+    describeFailure?: (() => string) | string;
+    expected?: unknown;
+    kind?: string;
+  }
 ): boolean;
 export declare function expectRowCount<T>(
   rows: T[],
@@ -452,7 +464,7 @@ export declare function expectNoRows<T>(
   label?: string | null
 ): boolean;
 export declare function expectField<T extends Record<string, unknown>>(
-  row: T,
+  row: T | T[],
   field: keyof T | string,
   predicateOrExpected: unknown | ((value: unknown) => boolean),
   label?: string | null
@@ -470,7 +482,7 @@ export declare function expectType(
 export declare function captureError(fn: () => unknown): unknown | null;
 export declare function expectError(
   errorOrFn: unknown | (() => unknown) | null,
-  predicate?: ((error: unknown) => boolean) | null,
+  predicate?: ((error: unknown) => boolean) | string | null,
   label?: string | null
 ): boolean;
 

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

@@ -3,6 +3,15 @@ import {
   extractErrorMessageFromBody,
   hasStandardErrorShape,
 } from "../shared/error-body.mjs";
+import {
+  buildValueAssertionDetail,
+  formatAssertionValue,
+  normalizeErrorValue,
+  resolveActual,
+  resolveConditionActual,
+  resolveConditionFailureMessage,
+  resolveFailureMessage,
+} from "../shared/assertion-details.mjs";
 import { safeJson, summarizeHttpTrace, toBodyPreview } from "./http.js";
 
 export function expectStatus(response, expected, label = null) {
@@ -140,16 +149,34 @@ export function expectResponse(response, predicate, label) {
   });
 }
 
-export function expectValue(value, predicate, label) {
-  return check(value, {
-    [normalizeLabel(label, "value matches expectation")]: predicate,
-  });
+export function expectValue(value, predicate, label, options = {}) {
+  const title = normalizeLabel(label, "value matches expectation");
+  return evaluateCheck(value, title, predicate, () =>
+    buildValueAssertionDetail({
+      kind: options.kind || "value-assertion",
+      title,
+      actual: resolveActual(value, options.actual),
+      expected: options.expected,
+      message: resolveFailureMessage(value, title, options.describeFailure),
+    })
+  );
 }
 
-export function expectCondition(predicate, label) {
-  return check(null, {
-    [normalizeLabel(label, "condition holds")]: () => Boolean(predicate()),
-  });
+export function expectCondition(predicate, label, options = {}) {
+  const title = normalizeLabel(label, "condition holds");
+  return evaluateCheck(
+    null,
+    title,
+    () => Boolean(predicate()),
+    () =>
+      buildValueAssertionDetail({
+        kind: options.kind || "condition-assertion",
+        title,
+        actual: resolveConditionActual(options.actual),
+        expected: options.expected,
+        message: resolveConditionFailureMessage(title, options.describeFailure),
+      })
+  );
 }
 
 export function expectRowCount(rows, expectedCount, label = null) {
@@ -160,7 +187,14 @@ export function expectRowCount(rows, expectedCount, label = null) {
   return expectValue(
     rows,
     (value) => Array.isArray(value) && value.length === expected,
-    normalizeLabel(label, `row count is ${expected}`)
+    normalizeLabel(label, `row count is ${expected}`),
+    {
+      actual: (value) => (Array.isArray(value) ? value.length : undefined),
+      describeFailure: (value) =>
+        `expected ${expected} row(s), got ${Array.isArray(value) ? value.length : "non-array value"}`,
+      expected,
+      kind: "row-count-assertion",
+    }
   );
 }
 
@@ -173,12 +207,23 @@ export function expectNoRows(rows, label = "query returns no rows") {
   return expectRowCount(rows, 0, label);
 }
 
-export function expectField(row, field, predicateOrExpected, label = null) {
+export function expectField(rowOrRows, field, predicateOrExpected, label = null) {
   const fieldName = String(field || "");
+  const row = Array.isArray(rowOrRows) ? rowOrRows[0] : rowOrRows;
+  const expected = typeof predicateOrExpected === "function" ? undefined : predicateOrExpected;
   return expectValue(
     row?.[fieldName],
     normalizeFieldPredicate(predicateOrExpected),
-    normalizeLabel(label, `${fieldName || "field"} matches expectation`)
+    normalizeLabel(label, `${fieldName || "field"} matches expectation`),
+    {
+      actual: row?.[fieldName],
+      describeFailure: () =>
+        Array.isArray(rowOrRows) && rowOrRows.length === 0
+          ? `expected ${fieldName || "field"}=${formatAssertionValue(expected)}, but query returned 0 rows`
+          : `${fieldName || "field"} expected ${formatAssertionValue(expected)}, got ${formatAssertionValue(row?.[fieldName])}`,
+      expected,
+      kind: "field-assertion",
+    }
   );
 }
 
@@ -198,7 +243,13 @@ export function expectType(value, typeName, label = null) {
   return expectValue(
     value,
     (actual) => actualType(actual) === expected,
-    normalizeLabel(label, `type is ${expected}`)
+    normalizeLabel(label, `type is ${expected}`),
+    {
+      actual: (actual) => actualType(actual),
+      describeFailure: (actual) => `expected type ${expected}, got ${actualType(actual)}`,
+      expected,
+      kind: "type-assertion",
+    }
   );
 }
 
@@ -213,13 +264,21 @@ export function captureError(fn) {
 
 export function expectError(errorOrFn, predicate = null, label = null) {
   const error = typeof errorOrFn === "function" ? captureError(errorOrFn) : errorOrFn;
+  const predicateFn = typeof predicate === "function" ? predicate : null;
+  const title = typeof predicate === "string" && label == null ? predicate : label;
   return expectValue(
     error,
     (value) => {
       if (!value) return false;
-      return typeof predicate === "function" ? Boolean(predicate(value)) : true;
+      return predicateFn ? Boolean(predicateFn(value)) : true;
     },
-    normalizeLabel(label, "error is captured")
+    normalizeLabel(title, "error is captured"),
+    {
+      actual: normalizeErrorValue(error),
+      describeFailure: () => "expected operation to throw",
+      expected: "error",
+      kind: "error-assertion",
+    }
   );
 }
 

package/lib/runtime-src/shared/assertion-details.mjs

@@ -0,0 +1,98 @@
+export function buildValueAssertionDetail({ actual, expected, kind, message, title }) {
+  const location = captureCallsite();
+  return {
+    kind,
+    key: location ? `${location.path}:${location.line}:${location.column}` : title,
+    title,
+    message,
+    expected: normalizeAssertionValue(expected),
+    actual: normalizeAssertionValue(actual),
+    location,
+  };
+}
+
+export function resolveActual(value, actual) {
+  if (typeof actual === "function") return actual(value);
+  if (actual !== undefined) return actual;
+  return value;
+}
+
+export function resolveConditionActual(actual) {
+  if (typeof actual === "function") return actual();
+  return actual;
+}
+
+export function resolveFailureMessage(value, label, describeFailure) {
+  if (typeof describeFailure === "function") return describeFailure(value);
+  if (typeof describeFailure === "string" && describeFailure.trim().length > 0) {
+    return describeFailure;
+  }
+  return label;
+}
+
+export function resolveConditionFailureMessage(label, describeFailure) {
+  if (typeof describeFailure === "function") return describeFailure();
+  if (typeof describeFailure === "string" && describeFailure.trim().length > 0) {
+    return describeFailure;
+  }
+  return label;
+}
+
+export function normalizeAssertionValue(value) {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string"
+  ) {
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+}
+
+export function formatAssertionValue(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === undefined) return "undefined";
+  if (typeof value === "bigint") return value.toString();
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export function normalizeErrorValue(error) {
+  if (!error) return null;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+function captureCallsite() {
+  const stack = new Error().stack;
+  if (!stack) return null;
+
+  for (const line of stack.split("\n").slice(1)) {
+    const match = line.match(/(file:\/\/[^\s)]+|\/[^\s):]+):(\d+):(\d+)/);
+    if (!match) continue;
+    const [rawPath, rawLine, rawColumn] = match.slice(1);
+    if (!rawPath || !rawLine || !rawColumn) continue;
+    const stackPath = rawPath.startsWith("file://") ? rawPath.slice("file://".length) : rawPath;
+    if (stackPath.endsWith("/runtime-src/shared/assertion-details.mjs")) continue;
+    if (stackPath.endsWith("/runtime-src/k6/http-assertions.js")) continue;
+    if (stackPath.endsWith("/runtime-src/k6/checks.js")) continue;
+    if (stackPath.endsWith("/runtime/index.mjs")) continue;
+    return {
+      path: stackPath,
+      line: Number(rawLine),
+      column: Number(rawColumn),
+    };
+  }
+
+  return null;
+}

package/lib/ui/index.d.ts

@@ -105,6 +105,19 @@ export declare function waitForAnimationFrames(
   page: import("@playwright/test").Page,
   frames?: number
 ): Promise<void>;
+export declare function waitForNetworkIdle(
+  page: import("@playwright/test").Page,
+  options?: { frames?: number; timeout?: number }
+): Promise<void>;
+export declare function waitForElementStable(
+  page: import("@playwright/test").Page,
+  selector: string,
+  options?: { frames?: number; timeout?: number }
+): Promise<void>;
+export declare function waitForImagesLoaded(
+  page: import("@playwright/test").Page,
+  containerSelector?: string | null
+): Promise<void>;
 export declare function readUiConfig(env?: NodeJS.ProcessEnv): unknown;
 export declare function provisionUiIdentity(
   page: import("@playwright/test").Page,

package/lib/ui/index.mjs

@@ -10,6 +10,9 @@ export {
   resolveBackendBaseUrl,
   resolveFrontendBaseUrl,
   waitForAnimationFrames,
+  waitForElementStable,
+  waitForImagesLoaded,
+  waitForNetworkIdle,
   waitForUiSettled,
 } from "./sandbox.mjs";
 export {

package/lib/ui/provisioning.mjs

@@ -196,20 +196,28 @@ async function runProvisionSql({ config, identity, options, profile, session, sq
   if (!databaseUrl) {
     throw new Error("UI provisioning SQL requires auth.databaseUrl, TESTKIT_UI_DATABASE_URL, or DATABASE_URL");
   }
-  for (const statement of sql) {
-    const rendered = renderSql(statement, { identity, options, profile, session });
-    const result = await execa("psql", [databaseUrl, "-v", "ON_ERROR_STOP=1", "-X", "-q", "-c", rendered], {
-      env: process.env,
-      reject: false,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(result.stderr || result.shortMessage || `UI provisioning SQL failed with exit code ${result.exitCode}`);
-    }
+  const renderedSql = sql
+    .map((statement) => renderSql(statement, { identity, options, profile, session }).trim())
+    .filter(Boolean)
+    .map(terminateSqlStatement)
+    .join("\n");
+  if (!renderedSql) return;
+
+  const result = await execa("psql", [databaseUrl, "-v", "ON_ERROR_STOP=1", "-X", "-q", "-c", renderedSql], {
+    env: process.env,
+    reject: false,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || result.shortMessage || `UI provisioning SQL failed with exit code ${result.exitCode}`);
   }
 }
 
+function terminateSqlStatement(statement) {
+  return /;\s*$/.test(statement) ? statement : `${statement};`;
+}
+
 function defaultSignupBody() {
   return {
     email: "{identity.email}",

package/lib/ui/sandbox.mjs

@@ -220,7 +220,7 @@ export async function waitForUiSettled(page, options = {}) {
   const timeout = options.timeout ?? 5_000;
   await page.waitForLoadState("domcontentloaded", { timeout });
   await waitForAnimationFrames(page, options.frames ?? 2);
-  await page.waitForLoadState("networkidle", { timeout }).catch(() => {});
+  await waitForNetworkIdle(page, { frames: options.frames ?? 2, timeout });
 }
 
 export async function waitForAnimationFrames(page, frames = 2) {
@@ -243,6 +243,52 @@ export async function waitForAnimationFrames(page, frames = 2) {
   );
 }
 
+export async function waitForNetworkIdle(page, options = {}) {
+  const timeout = options.timeout ?? 2_000;
+  try {
+    await page.waitForLoadState("networkidle", { timeout });
+  } catch {
+    await page.waitForLoadState("load", { timeout }).catch(() => {});
+    await waitForAnimationFrames(page, options.frames ?? 2);
+  }
+}
+
+export async function waitForElementStable(page, selector, options = {}) {
+  const stableFrames = Math.max(1, Number(options.frames) || 2);
+  const element = page.locator(selector);
+  await element.waitFor({ state: "visible", timeout: options.timeout });
+  await element.evaluate(async (node, requiredStableFrames) => {
+    let stable = 0;
+    let previous = JSON.stringify(node.getBoundingClientRect().toJSON());
+    while (stable < requiredStableFrames) {
+      await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+      const current = JSON.stringify(node.getBoundingClientRect().toJSON());
+      if (current === previous) {
+        stable += 1;
+      } else {
+        stable = 0;
+      }
+      previous = current;
+    }
+  }, stableFrames);
+}
+
+export async function waitForImagesLoaded(page, containerSelector = null) {
+  const selector = containerSelector ? `${containerSelector} img` : "img";
+  const images = page.locator(selector);
+  const count = await images.count();
+
+  for (let index = 0; index < count; index += 1) {
+    await images.nth(index).evaluate((element) => {
+      if (element.complete) return undefined;
+      return new Promise((resolve) => {
+        element.addEventListener("load", resolve, { once: true });
+        element.addEventListener("error", resolve, { once: true });
+      });
+    });
+  }
+}
+
 function resolveBaseUrl(value) {
   const normalized = String(value || "").trim();
   if (!normalized) {

package/node_modules/@elench/next-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "SWC-backed Next.js source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.132"
+    "@elench/testkit-protocol": "0.1.134"
   },
   "private": false
 }

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/node_modules/@elench/ts-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/ts-analysis",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -95,10 +95,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.132",
-    "@elench/testkit-bridge": "0.1.132",
-    "@elench/testkit-protocol": "0.1.132",
-    "@elench/ts-analysis": "0.1.132",
+    "@elench/next-analysis": "0.1.134",
+    "@elench/testkit-bridge": "0.1.134",
+    "@elench/testkit-protocol": "0.1.134",
+    "@elench/ts-analysis": "0.1.134",
     "@oclif/core": "^4.10.6",
     "@playwright/test": "^1.52.0",
     "esbuild": "^0.25.11",