@elench/testkit 0.1.118 → 0.1.120

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

@@ -251,6 +251,7 @@ function buildExecutionEnvWithContext(config, lease, extraEnv, processEnv, optio
 }
 
 export function buildPlaywrightEnv(config, baseUrl, lease, processEnv = process.env) {
+  const templateContext = buildTemplateContext(config, lease);
   return buildTaskExecutionEnv(
     config,
     lease,
@@ -260,6 +261,9 @@ export function buildPlaywrightEnv(config, baseUrl, lease, processEnv = process.
       PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS:
         processEnv.PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS || "1",
       TESTKIT_MANAGED_SERVERS: "1",
+      ...(config.testkit?.ui
+        ? { TESTKIT_UI_CONFIG_JSON: JSON.stringify(finalizeSerializable(config.testkit.ui, templateContext)) }
+        : {}),
     },
     processEnv
   );
@@ -300,6 +304,15 @@ export function finalizeString(value, context) {
   return resolved;
 }
 
+function finalizeSerializable(value, context) {
+  if (typeof value === "string") return finalizeString(value, context);
+  if (Array.isArray(value)) return value.map((entry) => finalizeSerializable(entry, context));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [key, finalizeSerializable(entry, context)])
+  );
+}
+
 export function resolveTemplateString(value, context) {
   if (typeof value !== "string") return value;
 

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,121 @@
 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 interface ProvisionedUiSandbox {
+  id: string;
+  backendBaseUrl: string;
+  frontendBaseUrl: string;
+  identity: unknown;
+  owner: {
+    email: string;
+    id: string;
+    name: string;
+    organizationId: string;
+    organizationName: string;
+    password: string;
+    slug: string;
+    timeZone: string | null;
+  };
+  ensureAuthenticated(page: import("@playwright/test").Page): Promise<void>;
+  apiFetch<T = unknown>(
+    page: import("@playwright/test").Page,
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+    path: string,
+    options?: Record<string, unknown>
+  ): Promise<T>;
+}
+export declare function createProvisionedUiSandbox(options?: UiSandboxOptions & Record<string, unknown>): {
+  expect: typeof import("@playwright/test").expect;
+  test: import("@playwright/test").TestType<
+    import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+      guestPage: import("@playwright/test").Page;
+      sandbox: ProvisionedUiSandbox;
+    },
+    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>;
+export declare function readUiConfig(env?: NodeJS.ProcessEnv): unknown;
+export declare function provisionUiIdentity(
+  page: import("@playwright/test").Page,
+  profileName?: string,
+  options?: Record<string, unknown>
+): Promise<{
+  credentials: { email: string; password: string };
+  organizations: unknown[];
+  profile: string;
+  seeded: Record<string, unknown>;
+  session: Record<string, unknown>;
+  token?: string;
+  user?: Record<string, unknown>;
+}>;
+export declare function loginWithCredentials(
+  page: import("@playwright/test").Page,
+  email: string,
+  password: string,
+  options?: Record<string, unknown>
+): Promise<void>;
+export declare function loginAsProvisioned(
+  page: import("@playwright/test").Page,
+  identity: { credentials: { email: string; password: string } },
+  options?: Record<string, unknown>
+): Promise<unknown>;
+export declare function loginAsUiProfile(
+  page: import("@playwright/test").Page,
+  profileName?: string,
+  options?: Record<string, unknown>
+): Promise<unknown>;
+export declare function persistUiSessionStorage(
+  page: import("@playwright/test").Page,
+  identity: unknown,
+  options?: Record<string, unknown>
+): Promise<void>;
+export declare function expectAuthenticatedShell(
+  page: import("@playwright/test").Page,
+  options?: Record<string, unknown>
+): Promise<void>;

package/lib/ui/index.mjs

@@ -1,2 +1,23 @@
 export * from "@playwright/test";
 export { defineConfig } from "../playwright/index.mjs";
+export {
+  assertSafeUiTarget,
+  assertSafeUiTargets,
+  createAuthedApiClient,
+  createProvisionedUiSandbox,
+  createSandboxId,
+  createUiSandbox,
+  resolveBackendBaseUrl,
+  resolveFrontendBaseUrl,
+  waitForAnimationFrames,
+  waitForUiSettled,
+} from "./sandbox.mjs";
+export {
+  expectAuthenticatedShell,
+  loginAsProvisioned,
+  loginAsUiProfile,
+  loginWithCredentials,
+  persistUiSessionStorage,
+  provisionUiIdentity,
+  readUiConfig,
+} from "./provisioning.mjs";