@elench/testkit 0.1.119 → 0.1.120

package/lib/cli/commands/lint.mjs

@@ -12,6 +12,10 @@ export default class LintCommand extends Command {
     dir: Flags.string({
       description: "Product directory",
     }),
+    "testkit-boundary": Flags.boolean({
+      description: "Fail when tracked Testkit plumbing exists outside testkit.config.* or __testkit__/ paths",
+      default: false,
+    }),
   };
 
   async run() {

package/lib/cli/operations/lint/operation.mjs

@@ -5,8 +5,16 @@ import { resolveProductDir } from "../../../config/paths.mjs";
 export async function executeLintOperation(flags = {}) {
   const productDir = resolveProductDir(process.cwd(), flags.dir);
   const { config } = await loadTestkitConfig(productDir);
+  const cliLint = flags["testkit-boundary"]
+    ? { rules: { testkitBoundary: true } }
+    : {};
   return runLint({
     dir: productDir,
     ...(config.lint || {}),
+    ...cliLint,
+    rules: {
+      ...(config.lint?.rules || {}),
+      ...(cliLint.rules || {}),
+    },
   });
 }

package/lib/config/index.mjs

@@ -167,6 +167,7 @@ function normalizeServiceConfig({
       skip,
       runtime,
       browser,
+      ui: config.ui || null,
       fileMetadataByPath: serviceFileMetadata,
       local,
     },

package/lib/config-api/database-steps.mjs

@@ -14,6 +14,70 @@ export async function verifySeed(context = {}) {
   }
 }
 
+export async function verifyRows(context = {}) {
+  const args = context.args || {};
+  const checks = Array.isArray(args.checks) ? args.checks : [args];
+  const databaseUrl = requireDatabaseUrl(context);
+  const failures = [];
+
+  for (const [index, check] of checks.entries()) {
+    const label = `verifyRows.args.checks[${index}]`;
+    const table = requireIdentifier(check.table, `${label}.table`);
+    const where = normalizeOptionalSql(check.where);
+    const minRows = normalizeNonNegativeInteger(check.minRows ?? 1, `${label}.minRows`);
+    const severity = check.severity === "warn" ? "warn" : "error";
+    const query = `select count(*)::int from ${table}${where ? ` where ${where}` : ""}`;
+    const count = Number(await runScalar(databaseUrl, query, context));
+
+    if (!Number.isInteger(count) || count < minRows) {
+      const message = `Expected at least ${minRows} row(s) in ${table}, found ${count || 0}`;
+      if (severity === "warn") {
+        console.warn(message);
+      } else {
+        failures.push(message);
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`Database row verification failed:\n${failures.map((failure) => `- ${failure}`).join("\n")}`);
+  }
+}
+
+export async function runSql(context = {}) {
+  const args = context.args || {};
+  const statements = normalizeStatementList(args.statements ?? args.statement, "runSql.args.statements");
+  const databaseUrl = requireDatabaseUrl(context);
+
+  for (const statement of statements) {
+    await runPsql(databaseUrl, statement, context);
+  }
+}
+
+export async function seedRows(context = {}) {
+  const args = context.args || {};
+  const table = requireIdentifier(args.table, "seedRows.args.table");
+  const rows = normalizeRowList(args.rows, "seedRows.args.rows");
+  const databaseUrl = requireDatabaseUrl(context);
+
+  if (args.truncate === true) {
+    await runPsql(databaseUrl, `truncate table ${table}`, context);
+  }
+
+  if (rows.length === 0) return;
+
+  const columns = normalizeSeedColumns(args.columns, rows);
+  const columnSql = columns.map((column) => requireIdentifier(column, `seedRows.args.columns.${column}`));
+  const valueGroups = rows.map((row) =>
+    `(${columns.map((column) => toSqlExpression(row[column], context)).join(", ")})`
+  );
+  await runPsql(
+    databaseUrl,
+    `insert into ${table} (${columnSql.join(", ")}) values ${valueGroups.join(", ")}`,
+    context
+  );
+}
+
 export async function materializePostgresBinding(context = {}) {
   const args = context.args || {};
   const table = requireIdentifier(args.table, "materializePostgresBinding.args.table");
@@ -44,6 +108,34 @@ export async function materializePostgresBinding(context = {}) {
   }
 }
 
+export async function updateRows(context = {}) {
+  const args = context.args || {};
+  const table = requireIdentifier(args.table, "updateRows.args.table");
+  const where = normalizeWhereObject(args.where, "updateRows.args.where");
+  const values = normalizeObject(args.values ?? args.set, "updateRows.args.values");
+  const databaseUrl = requireDatabaseUrl(context);
+  const expectRows = args.expectRows == null
+    ? null
+    : normalizeNonNegativeInteger(args.expectRows, "updateRows.args.expectRows");
+
+  const assignments = Object.keys(values).map((column) => {
+    const identifier = requireIdentifier(column, `updateRows.args.values.${column}`);
+    return `${identifier} = ${toSqlExpression(values[column], context)}`;
+  });
+  if (assignments.length === 0) {
+    throw new Error("updateRows.args.values must contain at least one column");
+  }
+
+  const query =
+    `with updated as (update ${table} set ${assignments.join(", ")} ` +
+    `where ${buildWhereClause(where, context)} returning 1) select count(*)::int from updated`;
+  const result = await runPsql(databaseUrl, query, context);
+  const updated = Number(String(result.stdout || "").trim() || "0");
+  if (expectRows !== null && updated !== expectRows) {
+    throw new Error(`Expected to update ${expectRows} ${table} row(s), updated ${updated || 0}`);
+  }
+}
+
 function requireDatabaseUrl(context) {
   const databaseUrl = String(context.databaseUrl || context.env?.DATABASE_URL || "").trim();
   if (!databaseUrl) {
@@ -85,6 +177,54 @@ async function runPsql(databaseUrl, query, context) {
   return result;
 }
 
+function normalizeStatementList(value, label) {
+  const values = Array.isArray(value) ? value : value == null ? [] : [value];
+  if (values.length === 0) {
+    throw new Error(`${label} must contain at least one SQL statement`);
+  }
+  return values.map((statement, index) => {
+    const normalized = String(statement || "").trim();
+    if (!normalized || /;\s*\S/.test(normalized)) {
+      throw new Error(`${label}[${index}] must be one SQL statement`);
+    }
+    return normalized;
+  });
+}
+
+function normalizeRowList(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  return value.map((row, index) => normalizeObject(row, `${label}[${index}]`));
+}
+
+function normalizeSeedColumns(value, rows) {
+  if (value != null) {
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new Error("seedRows.args.columns must be a non-empty array");
+    }
+    return value.map((column) => String(column));
+  }
+  return [...new Set(rows.flatMap((row) => Object.keys(row)))].sort((left, right) => left.localeCompare(right));
+}
+
+function normalizeWhereObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    throw new Error(`${label} must contain at least one column`);
+  }
+  return value;
+}
+
+function buildWhereClause(where, context) {
+  return Object.entries(where)
+    .map(([column, value]) => `${requireIdentifier(column, `where.${column}`)} = ${toSqlExpression(value, context)}`)
+    .join(" and ");
+}
+
 function requireIdentifier(value, label) {
   const normalized = String(value || "").trim();
   if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(normalized)) {
@@ -130,3 +270,71 @@ function toSqlLiteral(value) {
   if (typeof value === "boolean") return value ? "true" : "false";
   return `'${String(value).replaceAll("'", "''")}'`;
 }
+
+function toSqlExpression(value, context) {
+  if (!isValueDescriptor(value)) return toSqlLiteral(value);
+  switch (value.kind) {
+    case "now":
+      return "now()";
+    case "env":
+      return toSqlLiteral(readRequiredEnv(context.env || process.env, value.name));
+    case "json":
+      return `${toSqlLiteral(JSON.stringify(resolveJsonValue(value.value, context)))}::jsonb`;
+    case "postgres-connection-from-env":
+      return `${toSqlLiteral(JSON.stringify(buildPostgresConnectionFromEnv(context.env || process.env, value.prefix)))}::jsonb`;
+    default:
+      throw new Error(`Unsupported database value descriptor "${value.kind}"`);
+  }
+}
+
+function isValueDescriptor(value) {
+  return value && typeof value === "object" && !Array.isArray(value) && typeof value.kind === "string";
+}
+
+function resolveJsonValue(value, context) {
+  if (Array.isArray(value)) return value.map((entry) => resolveJsonValue(entry, context));
+  if (!value || typeof value !== "object") return value;
+  if (isValueDescriptor(value)) {
+    if (value.kind === "env") return readRequiredEnv(context.env || process.env, value.name);
+    if (value.kind === "postgres-connection-from-env") {
+      return buildPostgresConnectionFromEnv(context.env || process.env, value.prefix);
+    }
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolveJsonValue(entry, context)]));
+}
+
+function buildPostgresConnectionFromEnv(env, prefix) {
+  const normalizedPrefix = String(prefix || "").trim();
+  if (!normalizedPrefix) {
+    throw new Error("postgresConnectionFromEnv requires a non-empty prefix");
+  }
+  return {
+    host: readRequiredEnv(env, `${normalizedPrefix}_HOST`),
+    port: readRequiredPort(env, `${normalizedPrefix}_PORT`),
+    database: readRequiredEnv(env, `${normalizedPrefix}_NAME`),
+    username: readRequiredEnv(env, `${normalizedPrefix}_USER`),
+    password: readRequiredEnv(env, `${normalizedPrefix}_PASSWORD`),
+    ssl: parseBooleanEnv(env[`${normalizedPrefix}_SSL`]),
+  };
+}
+
+function readRequiredEnv(env, name) {
+  const value = env?.[name];
+  if (value == null || String(value).trim().length === 0) {
+    throw new Error(`${name} environment variable is required`);
+  }
+  return String(value).trim();
+}
+
+function readRequiredPort(env, name) {
+  const value = Number.parseInt(readRequiredEnv(env, name), 10);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return value;
+}
+
+function parseBooleanEnv(value) {
+  if (!value) return false;
+  return ["1", "true", "yes", "on"].includes(String(value).trim().toLowerCase());
+}

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

@@ -163,6 +163,81 @@ export interface RegressionSyncConfig {
   cacheTtlSeconds?: number;
 }
 
+export interface TestkitBoundaryLintConfig {
+  allowed?: string[];
+  severity?: "error" | "warn" | false;
+  trackedOnly?: boolean;
+}
+
+export interface TestkitLintConfig {
+  disable?: string[];
+  rules?: Partial<Record<
+    | "missingImports"
+    | "uiRuntimeImports"
+    | "uiSpecShape"
+    | "dalParallelSafety"
+    | "legacyHttpAssertions"
+    | "legacyDalAssertions"
+    | "configImports",
+    boolean
+  >> & {
+    testkitBoundary?: TestkitBoundaryLintConfig | boolean;
+  };
+  testkitBoundary?: TestkitBoundaryLintConfig | boolean;
+  ui?: {
+    maxLines?: number;
+    maxTests?: number;
+  };
+}
+
+export interface UiProvisionProfileConfig {
+  afterSignupSql?: string | string[];
+  email?: string;
+  emailDomain?: string;
+  loginBody?: Record<string, unknown>;
+  loginExpect?: number | number[];
+  loginPath?: string;
+  name?: string;
+  organizationName?: string;
+  password?: string;
+  sessionPath?: string;
+  signup?: false;
+  signupBody?: Record<string, unknown>;
+  signupExpect?: number | number[];
+  signupPath?: string;
+}
+
+export interface UiAuthConfig {
+  afterSignupSql?: string | string[];
+  authenticatedSelector?: string;
+  backendBaseUrl?: string;
+  browserState?: {
+    localStorage?: Record<string, unknown>;
+  };
+  databaseUrl?: string;
+  emailSelector?: string;
+  frontendBaseUrl?: string;
+  homePath?: string;
+  loginBody?: Record<string, unknown>;
+  loginExpect?: number | number[];
+  loginPagePath?: string;
+  loginPath?: string;
+  passwordSelector?: string;
+  profiles?: Record<string, UiProvisionProfileConfig>;
+  sessionPath?: string;
+  signup?: false;
+  signupBody?: Record<string, unknown>;
+  signupExpect?: number | number[];
+  signupPath?: string;
+  storage?: Record<string, unknown>;
+  storagePath?: string;
+  submitSelector?: string;
+}
+
+export interface UiConfig {
+  auth?: UiAuthConfig;
+}
+
 export interface DiscoveryConfig {
   roots?: string[];
   exclude?: string[];
@@ -401,6 +476,7 @@ export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime"
 export interface TestkitConfig {
   discovery?: DiscoveryConfig;
   execution?: TestkitExecutionConfig;
+  lint?: TestkitLintConfig;
   profiles?: {
     http?: Record<string, HttpSuiteConfig<any>>;
   };
@@ -416,6 +492,7 @@ export interface TestkitConfig {
     timeoutMs?: number;
     tokenEnv?: string;
   };
+  ui?: UiConfig;
 }
 
 export interface NodeNextPresetOptions {
@@ -438,8 +515,18 @@ export declare const database: {
   };
   steps: {
     materializePostgresBinding(options?: unknown): TemplateModuleStepConfig;
+    runSql(options?: unknown): TemplateModuleStepConfig;
+    seedRows(options?: unknown): TemplateModuleStepConfig;
+    updateRows(options?: unknown): TemplateModuleStepConfig;
+    verifyRows(options?: unknown): TemplateModuleStepConfig;
     verifySeed(options?: unknown): TemplateModuleStepConfig;
   };
+  values: {
+    env(name: string): unknown;
+    json(value: unknown): unknown;
+    now(): unknown;
+    postgresConnectionFromEnv(prefix: string): unknown;
+  };
   postgres(
     options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
       inputs?: string[];
@@ -472,6 +559,9 @@ export declare const presets: {
 export declare const toolchain: {
   node(options?: NodeToolchainConfig): NodeToolchainConfig;
 };
+export declare const ui: {
+  auth(options?: UiAuthConfig): UiConfig;
+};
 export declare const auth: {
   fixture(options: { contract: JsonSessionContract; topology: AuthTopology }): AuthFixture;
   contracts: {

package/lib/config-api/index.mjs

@@ -109,10 +109,45 @@ function verifySeedStep(options = {}) {
   return moduleStep(databaseStepTarget("verifySeed"), { args: options });
 }
 
+function verifyRowsStep(options = {}) {
+  return moduleStep(databaseStepTarget("verifyRows"), { args: options });
+}
+
+function runSqlStep(options = {}) {
+  return moduleStep(databaseStepTarget("runSql"), { args: options });
+}
+
+function seedRowsStep(options = {}) {
+  return moduleStep(databaseStepTarget("seedRows"), { args: options });
+}
+
 function materializePostgresBindingStep(options = {}) {
   return moduleStep(databaseStepTarget("materializePostgresBinding"), { args: options });
 }
 
+function updateRowsStep(options = {}) {
+  return moduleStep(databaseStepTarget("updateRows"), { args: options });
+}
+
+function nowValue() {
+  return { kind: "now" };
+}
+
+function envValue(name) {
+  return { kind: "env", name: normalizeDatabaseEnvToken(name, "database.values.env(...) name", false) };
+}
+
+function jsonValue(value) {
+  return { kind: "json", value };
+}
+
+function postgresConnectionFromEnvValue(prefix) {
+  return {
+    kind: "postgres-connection-from-env",
+    prefix: normalizeDatabaseEnvToken(prefix, "database.values.postgresConnectionFromEnv(...) prefix", false),
+  };
+}
+
 function postgresFixture(options = {}) {
   const { discovery, envFiles, template, inputs, migrate, seed, verify, ...databaseOptions } = options;
   for (const legacyKey of ["schema"]) {
@@ -155,6 +190,15 @@ function nodeToolchain(options = {}) {
   };
 }
 
+function uiAuth(options = {}) {
+  return {
+    auth: {
+      ...options,
+      ...(options.profiles ? { profiles: { ...options.profiles } } : {}),
+    },
+  };
+}
+
 function tscBuild(options = {}) {
   return {
     kind: "tsc",
@@ -326,8 +370,18 @@ export const database = {
   },
   steps: {
     materializePostgresBinding: materializePostgresBindingStep,
+    runSql: runSqlStep,
+    seedRows: seedRowsStep,
+    updateRows: updateRowsStep,
+    verifyRows: verifyRowsStep,
     verifySeed: verifySeedStep,
   },
+  values: {
+    env: envValue,
+    json: jsonValue,
+    now: nowValue,
+    postgresConnectionFromEnv: postgresConnectionFromEnvValue,
+  },
   postgres(options = {}) {
     const { template, sourceSchema, inputs, migrate, seed, verify, ...databaseOptions } = options;
     for (const legacyKey of ["schema"]) {
@@ -386,6 +440,10 @@ export const toolchain = {
   node: nodeToolchain,
 };
 
+export const ui = {
+  auth: uiAuth,
+};
+
 export const auth = {
   fixture: createAuthFixture,
   contracts: {

package/lib/lint/index.mjs

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import ts from "typescript";
+import { execa } from "execa";
 import { findConfigFile } from "../config/config-loader.mjs";
 import { normalizePath } from "../config/paths.mjs";
 
@@ -17,6 +18,15 @@ const DEFAULT_EXCLUDED_DIRS = new Set([
 
 const DEFAULT_UI_MAX_LINES = 220;
 const DEFAULT_UI_MAX_TESTS = 8;
+const DEFAULT_TESTKIT_BOUNDARY_ALLOWED = [
+  "testkit.config.ts",
+  "testkit.config.mts",
+  "testkit.config.mjs",
+  "testkit.config.js",
+  "testkit.regressions.json",
+  "testkit.status.json",
+  "**/__testkit__/**",
+];
 
 export async function runLint(options = {}) {
   const productDir = path.resolve(process.cwd(), options.dir || ".");
@@ -47,14 +57,19 @@ export async function runLint(options = {}) {
   if (lintOptions.rules.configImports) {
     violations.push(...findConfigImportViolations(productDir));
   }
+  if (lintOptions.rules.testkitBoundary) {
+    violations.push(...await findTestkitBoundaryViolations(productDir, lintOptions.testkitBoundary));
+  }
 
   const sortedViolations = violations.sort(compareViolations);
+  const errors = sortedViolations.filter((entry) => entry.severity !== "warn").length;
   return {
-    ok: sortedViolations.length === 0,
+    ok: errors === 0,
     productDir,
     summary: {
       files: files.length,
       testkitFiles: testkitFiles.length,
+      errors,
       violations: sortedViolations.length,
     },
     violations: sortedViolations,
@@ -77,10 +92,14 @@ function normalizeLintOptions(options = {}) {
     legacyHttpAssertions: true,
     legacyDalAssertions: true,
     configImports: true,
+    testkitBoundary: false,
   };
+  const boundaryConfig = normalizeBoundaryConfig(options.testkitBoundary ?? rules.testkitBoundary);
 
   for (const [ruleName, value] of Object.entries(rules)) {
-    if (Object.prototype.hasOwnProperty.call(enabled, ruleName)) {
+    if (ruleName === "testkitBoundary") {
+      enabled.testkitBoundary = value !== false && value != null;
+    } else if (Object.prototype.hasOwnProperty.call(enabled, ruleName)) {
       enabled[ruleName] = value !== false;
     }
   }
@@ -96,6 +115,34 @@ function normalizeLintOptions(options = {}) {
       maxLines: normalizePositiveInteger(options.ui?.maxLines, DEFAULT_UI_MAX_LINES),
       maxTests: normalizePositiveInteger(options.ui?.maxTests, DEFAULT_UI_MAX_TESTS),
     },
+    testkitBoundary: boundaryConfig,
+  };
+}
+
+function normalizeBoundaryConfig(value) {
+  if (value === false || value == null) {
+    return {
+      allowed: DEFAULT_TESTKIT_BOUNDARY_ALLOWED,
+      severity: "error",
+      trackedOnly: true,
+    };
+  }
+  if (value === true) {
+    return {
+      allowed: DEFAULT_TESTKIT_BOUNDARY_ALLOWED,
+      severity: "error",
+      trackedOnly: true,
+    };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("lint testkitBoundary config must be an object, true, or false");
+  }
+  return {
+    allowed: Array.isArray(value.allowed) && value.allowed.length > 0
+      ? value.allowed.map((entry) => normalizePath(String(entry)))
+      : DEFAULT_TESTKIT_BOUNDARY_ALLOWED,
+    severity: value.severity === "warn" ? "warn" : "error",
+    trackedOnly: value.trackedOnly !== false,
   };
 }
 
@@ -554,6 +601,79 @@ function findConfigImportViolations(productDir) {
   return violations;
 }
 
+async function findTestkitBoundaryViolations(productDir, options) {
+  const candidates = options.trackedOnly
+    ? await collectTrackedFiles(productDir)
+    : collectAllFilePaths(productDir);
+  const violations = [];
+  for (const file of candidates) {
+    if (!hasTestkitPathSegment(file)) continue;
+    if (isAllowedTestkitBoundaryPath(file, options.allowed)) continue;
+    violations.push({
+      ruleId: "testkit-boundary",
+      severity: options.severity,
+      file,
+      line: 1,
+      message:
+        "Tracked Testkit plumbing must live in testkit.config.* or __testkit__/ suites, or move into @elench/testkit",
+    });
+  }
+  return violations;
+}
+
+async function collectTrackedFiles(productDir) {
+  const result = await execa("git", ["ls-files", "-z"], {
+    cwd: productDir,
+    reject: false,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    return collectAllFilePaths(productDir);
+  }
+  return String(result.stdout || "")
+    .split("\0")
+    .map((entry) => normalizePath(entry))
+    .filter(Boolean)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function collectAllFilePaths(productDir) {
+  return collectSourceFiles(productDir)
+    .map((filePath) => relative(productDir, filePath))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function hasTestkitPathSegment(file) {
+  return normalizePath(file)
+    .split("/")
+    .some((part) => part.toLowerCase().includes("testkit"));
+}
+
+function isAllowedTestkitBoundaryPath(file, patterns) {
+  return patterns.some((pattern) => matchBoundaryPattern(file, pattern));
+}
+
+function matchBoundaryPattern(file, pattern) {
+  const normalizedFile = normalizePath(file);
+  const normalizedPattern = normalizePath(pattern);
+  if (normalizedPattern === normalizedFile) return true;
+  if (normalizedPattern === "**/__testkit__/**") {
+    return normalizedFile.split("/").includes("__testkit__");
+  }
+  if (normalizedPattern.startsWith("**/") && normalizedPattern.endsWith("/**")) {
+    const segment = normalizedPattern.slice(3, -3);
+    return normalizedFile.split("/").includes(segment);
+  }
+  if (normalizedPattern.endsWith("/**")) {
+    return normalizedFile.startsWith(normalizedPattern.slice(0, -3));
+  }
+  if (normalizedPattern.startsWith("**/")) {
+    return normalizedFile.endsWith(normalizedPattern.slice(3));
+  }
+  return false;
+}
+
 function visit(node, fn) {
   fn(node);
   ts.forEachChild(node, (child) => visit(child, fn));

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;