@elench/testkit 0.1.118 → 0.1.120

package/lib/ui/provisioning.mjs

@@ -0,0 +1,283 @@
+import { randomUUID } from "crypto";
+import { execa } from "execa";
+import { expect } from "@playwright/test";
+import {
+  assertSafeUiTarget,
+  resolveBackendBaseUrl,
+  resolveFrontendBaseUrl,
+  waitForUiSettled,
+} from "./sandbox.mjs";
+
+const DEFAULT_PASSWORD = "TestkitPass2026";
+
+export function readUiConfig(env = process.env) {
+  const raw = env.TESTKIT_UI_CONFIG_JSON;
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (error) {
+    throw new Error(`TESTKIT_UI_CONFIG_JSON is not valid JSON: ${error?.message || error}`);
+  }
+}
+
+export async function provisionUiIdentity(page, profileName = "default", options = {}) {
+  const config = resolveAuthConfig(options.config);
+  const profile = resolveProfileConfig(config, profileName);
+  const backendBaseUrl = assertSafeUiTarget(
+    options.backendBaseUrl || config.backendBaseUrl || resolveBackendBaseUrl({ backendBaseUrl: config.backendBaseUrl })
+  );
+  const identity = buildIdentity(profileName, profile, options);
+  const request = page.context().request;
+
+  if (profile.signup !== false && config.signup !== false) {
+    const signupResponse = await request.post(`${backendBaseUrl}${profile.signupPath || config.signupPath || "/api/v1/auth/signup"}`, {
+      data: renderTemplateValue(profile.signupBody || config.signupBody || defaultSignupBody(), {
+        identity,
+        options,
+        profile: profileName,
+      }),
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!isExpectedStatus(signupResponse.status(), profile.signupExpect || config.signupExpect || [201, 409])) {
+      throw await responseError(signupResponse, `Signup for UI profile "${profileName}"`);
+    }
+  }
+
+  let session = await login({ backendBaseUrl, config, identity, page, profile, profileName });
+  const sql = [...normalizeSqlList(config.afterSignupSql), ...normalizeSqlList(profile.afterSignupSql)];
+  if (sql.length > 0) {
+    await runProvisionSql({
+      config,
+      identity,
+      options,
+      profile: profileName,
+      session,
+      sql,
+    });
+    session = await login({ backendBaseUrl, config, identity, page, profile, profileName });
+  }
+
+  return {
+    credentials: {
+      email: identity.email,
+      password: identity.password,
+    },
+    organizations: Array.isArray(session.organizations) ? session.organizations : [],
+    profile: profileName,
+    seeded: {},
+    session,
+    token: session.token,
+    user: session.user,
+  };
+}
+
+export async function loginWithCredentials(page, email, password, options = {}) {
+  const config = resolveAuthConfig(options.config);
+  const frontendBaseUrl = assertSafeUiTarget(
+    options.frontendBaseUrl || config.frontendBaseUrl || resolveFrontendBaseUrl(options)
+  );
+  const loginPath = options.loginPagePath || config.loginPagePath || "/login";
+  const homePath = options.homePath || config.homePath || "/";
+
+  await page.goto(`${frontendBaseUrl}${loginPath}`);
+  await page.waitForLoadState("domcontentloaded");
+  await page.locator(options.emailSelector || config.emailSelector || 'input[type="email"], input#email').first().fill(email);
+  await page.locator(options.passwordSelector || config.passwordSelector || 'input[type="password"]').first().fill(password);
+  await page.locator(options.submitSelector || config.submitSelector || 'button[type="submit"]').first().click();
+  await page.waitForURL(`${frontendBaseUrl}${homePath}`, { timeout: options.timeout ?? 15_000 }).catch(async () => {
+    await page.waitForURL(homePath, { timeout: options.timeout ?? 15_000 });
+  });
+  await waitForUiSettled(page, options);
+}
+
+export async function loginAsProvisioned(page, identity, options = {}) {
+  await loginWithCredentials(page, identity.credentials.email, identity.credentials.password, options);
+  return identity;
+}
+
+export async function loginAsUiProfile(page, profileName = "default", options = {}) {
+  const identity = await provisionUiIdentity(page, profileName, options);
+  await loginWithCredentials(page, identity.credentials.email, identity.credentials.password, options);
+  return identity;
+}
+
+export async function persistUiSessionStorage(page, identity, options = {}) {
+  const config = resolveAuthConfig(options.config);
+  const storage = options.storage || config.storage || config.browserState?.localStorage || {};
+  const frontendBaseUrl = assertSafeUiTarget(
+    options.frontendBaseUrl || config.frontendBaseUrl || resolveFrontendBaseUrl(options)
+  );
+  await page.goto(`${frontendBaseUrl}${options.path || config.storagePath || "/login"}`);
+  await page.waitForLoadState("domcontentloaded");
+  await page.evaluate(
+    ({ identity: serializedIdentity, storageConfig }) => {
+      for (const [key, value] of Object.entries(storageConfig)) {
+        if (value === null || value === undefined) {
+          localStorage.removeItem(key);
+        } else if (typeof value === "string") {
+          localStorage.setItem(key, value);
+        } else {
+          localStorage.setItem(key, JSON.stringify(value));
+        }
+      }
+      window.dispatchEvent(new CustomEvent("testkit:session-storage", { detail: serializedIdentity }));
+    },
+    {
+      identity,
+      storageConfig: renderTemplateValue(storage, {
+        identity,
+        options,
+        profile: identity.profile,
+        session: identity.session,
+      }),
+    }
+  );
+}
+
+export async function expectAuthenticatedShell(page, options = {}) {
+  const config = resolveAuthConfig(options.config);
+  await expect(page.locator(options.selector || config.authenticatedSelector || 'button[aria-label="User menu"], button:has-text("User menu")').first()).toBeVisible({
+    timeout: options.timeout ?? 10_000,
+  });
+}
+
+function resolveAuthConfig(explicitConfig) {
+  const root = explicitConfig || readUiConfig();
+  const auth = root.auth || root;
+  if (!auth || typeof auth !== "object") {
+    throw new Error("Testkit UI auth config is required");
+  }
+  return auth;
+}
+
+function resolveProfileConfig(config, profileName) {
+  const profiles = config.profiles || {};
+  const profile = profiles[profileName] || profiles.default || {};
+  if (!profile || typeof profile !== "object") {
+    throw new Error(`UI profile "${profileName}" must be an object`);
+  }
+  return profile;
+}
+
+function buildIdentity(profileName, profile, options) {
+  const id = slugify(options.id || `${profileName}-${randomUUID()}`);
+  const domain = profile.emailDomain || options.emailDomain || "example.test";
+  return {
+    id,
+    email: renderTemplate(profile.email || `{identity.id}@${domain}`, { identity: { id }, options, profile: profileName }),
+    name: renderTemplate(profile.name || `Testkit ${profileName} {identity.id}`, { identity: { id }, options, profile: profileName }),
+    organizationName: renderTemplate(profile.organizationName || `Testkit ${profileName} {identity.id}`, {
+      identity: { id },
+      options,
+      profile: profileName,
+    }),
+    password: options.password || profile.password || DEFAULT_PASSWORD,
+  };
+}
+
+async function login({ backendBaseUrl, config, identity, page, profile, profileName }) {
+  const response = await page.context().request.post(`${backendBaseUrl}${profile.loginPath || config.loginPath || "/api/v1/auth/login"}`, {
+    data: renderTemplateValue(profile.loginBody || config.loginBody || defaultLoginBody(), {
+      identity,
+      profile: profileName,
+    }),
+    headers: { "Content-Type": "application/json" },
+  });
+  if (!isExpectedStatus(response.status(), profile.loginExpect || config.loginExpect || 200)) {
+    throw await responseError(response, `Login for UI profile "${profileName}"`);
+  }
+  const payload = await response.json().catch(() => ({}));
+  return readPath(payload, profile.sessionPath || config.sessionPath || "data") || payload;
+}
+
+async function runProvisionSql({ config, identity, options, profile, session, sql }) {
+  const databaseUrl = config.databaseUrl || process.env.TESTKIT_UI_DATABASE_URL || process.env.DATABASE_URL;
+  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}`);
+    }
+  }
+}
+
+function defaultSignupBody() {
+  return {
+    email: "{identity.email}",
+    name: "{identity.name}",
+    organizationName: "{identity.organizationName}",
+    password: "{identity.password}",
+  };
+}
+
+function defaultLoginBody() {
+  return {
+    email: "{identity.email}",
+    password: "{identity.password}",
+  };
+}
+
+function normalizeSqlList(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function renderTemplateValue(value, context) {
+  if (typeof value === "string") return renderTemplate(value, context);
+  if (Array.isArray(value)) return value.map((entry) => renderTemplateValue(entry, context));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, renderTemplateValue(entry, context)]));
+}
+
+function renderTemplate(value, context) {
+  return String(value).replace(/\{([A-Za-z0-9_.[\]-]+)\}/g, (_match, key) => {
+    const resolved = readPath(context, key);
+    return resolved == null ? "" : String(resolved);
+  });
+}
+
+function renderSql(statement, context) {
+  return String(statement).replace(/\{([A-Za-z0-9_.[\]-]+)\}/g, (_match, key) => toSqlLiteral(readPath(context, key)));
+}
+
+function readPath(source, path) {
+  return String(path)
+    .replace(/\[(\d+)\]/g, ".$1")
+    .split(".")
+    .filter(Boolean)
+    .reduce((value, part) => (value == null ? undefined : value[part]), source);
+}
+
+function toSqlLiteral(value) {
+  if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return `array[${value.map((entry) => toSqlLiteral(entry)).join(", ")}]`;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function isExpectedStatus(status, expected) {
+  return Array.isArray(expected) ? expected.includes(status) : status === expected;
+}
+
+async function responseError(response, label) {
+  const text = await response.text().catch(() => "");
+  return new Error(`${label} failed (${response.status()}): ${text || "no response body"}`);
+}
+
+function slugify(value) {
+  return String(value || "test")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64) || "test";
+}

package/lib/ui/sandbox.mjs

@@ -0,0 +1,250 @@
+import { expect, request, test as base } from "@playwright/test";
+
+export function createUiSandbox(options = {}) {
+  const sandboxId = createSandboxId(options);
+  return {
+    expect,
+    test: base.extend({
+      testkitSandbox: async ({ page }, use) => {
+        await use({
+          id: sandboxId,
+          backendBaseUrl: resolveBackendBaseUrl(options),
+          frontendBaseUrl: resolveFrontendBaseUrl(options),
+          page,
+        });
+      },
+    }),
+  };
+}
+
+export function createProvisionedUiSandbox(options = {}) {
+  return {
+    expect,
+    test: base.extend({
+      sandbox: async ({}, use, testInfo) => {
+        await use(new ProvisionedUiSandbox(testInfo, options));
+      },
+      guestPage: async ({ browser }, use, testInfo) => {
+        const frontendBaseUrl = resolveFrontendBaseUrlFromTestInfo(testInfo, options);
+        let context = null;
+        try {
+          context = await browser.newContext({
+            baseURL: frontendBaseUrl,
+          });
+          await use(await context.newPage());
+        } finally {
+          await context?.close();
+        }
+      },
+      page: async ({ page, sandbox }, use) => {
+        await sandbox.ensureAuthenticated(page);
+        await use(page);
+      },
+    }),
+  };
+}
+
+export function createSandboxId(options = {}) {
+  const prefix =
+    String(options.prefix || "ui").replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "ui";
+  const worker = process.env.TEST_WORKER_INDEX || process.env.TESTKIT_WORKER_INDEX || "0";
+  const run = process.env.TESTKIT_LEASE_ID || process.env.TESTKIT_RUNTIME_ID || process.pid;
+  return `${prefix}-${run}-${worker}`;
+}
+
+export function resolveFrontendBaseUrl(options = {}) {
+  return resolveBaseUrl(
+    options.frontendBaseUrl ||
+      options.baseUrl ||
+      process.env.TESTKIT_FRONTEND_BASE_URL ||
+      process.env.BASE_URL
+  );
+}
+
+export function resolveBackendBaseUrl(options = {}) {
+  return resolveBaseUrl(options.backendBaseUrl || process.env.TESTKIT_BACKEND_BASE_URL || process.env.API_BASE_URL);
+}
+
+export function assertSafeUiTarget(url, options = {}) {
+  const parsed = parseUrl(url);
+  if (!parsed) {
+    throw new Error(`Invalid UI target URL: ${url}`);
+  }
+  if (options.allowRemote === true) return parsed.toString().replace(/\/$/, "");
+  if (!isLocalHost(parsed.hostname)) {
+    throw new Error(`UI target must be local unless allowRemote is true: ${url}`);
+  }
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export function assertSafeUiTargets(urls = [], options = {}) {
+  return urls.map((url) => assertSafeUiTarget(url, options));
+}
+
+export async function createAuthedApiClient(playwrightRequest = request, options = {}) {
+  const baseURL = assertSafeUiTarget(resolveBackendBaseUrl(options), options);
+  return playwrightRequest.newContext({
+    baseURL,
+    extraHTTPHeaders: options.headers || {},
+  });
+}
+
+class ProvisionedUiSandbox {
+  constructor(testInfo, options = {}) {
+    this.authInFlight = null;
+    this.authenticated = false;
+    this.identity = null;
+    this.options = options;
+    this.id = createSandboxId({
+      prefix: options.prefix || buildStableTestPrefix(testInfo),
+    });
+    this.frontendBaseUrl = resolveFrontendBaseUrlFromTestInfo(testInfo, options);
+    this.backendBaseUrl = resolveBackendBaseUrl(options);
+  }
+
+  get owner() {
+    const identity = this.requireIdentity();
+    const organization = selectHomeOrganization(identity);
+    return {
+      email: identity.credentials.email,
+      id: identity.user?.id || "",
+      name: identity.user?.name || identity.credentials.email,
+      organizationId: organization?.id || "",
+      organizationName: organization?.name || "",
+      password: identity.credentials.password,
+      slug: organization?.slug || "",
+      timeZone: identity.user?.timeZone ?? null,
+    };
+  }
+
+  async ensureAuthenticated(page) {
+    if (this.authenticated) return;
+    if (!this.authInFlight) {
+      this.authInFlight = (async () => {
+        const {
+          expectAuthenticatedShell,
+          persistUiSessionStorage,
+          provisionUiIdentity,
+        } = await import("./provisioning.mjs");
+        this.identity = await provisionUiIdentity(page, this.options.profile || "owner", {
+          ...this.options,
+          backendBaseUrl: this.backendBaseUrl,
+          frontendBaseUrl: this.frontendBaseUrl,
+          id: this.id,
+        });
+        if (this.options.persistStorage !== false) {
+          await persistUiSessionStorage(page, this.identity, {
+            ...this.options,
+            frontendBaseUrl: this.frontendBaseUrl,
+          });
+          await page.goto(this.frontendBaseUrl);
+          await expectAuthenticatedShell(page, this.options);
+        }
+        this.authenticated = true;
+      })().finally(() => {
+        this.authInFlight = null;
+      });
+    }
+    await this.authInFlight;
+  }
+
+  async apiFetch(page, method, path, options = {}) {
+    await this.ensureAuthenticated(page);
+    const identity = this.requireIdentity();
+    const organization = selectHomeOrganization(identity);
+    const requestOptions = {
+      method,
+      headers: {
+        ...(identity.token ? { Authorization: `Bearer ${identity.token}` } : {}),
+        ...(organization?.id ? { "X-Organization-Id": organization.id } : {}),
+        ...(options.headers || {}),
+      },
+      ...(options.data !== undefined ? { data: options.data } : {}),
+      ...(options.multipart !== undefined ? { multipart: options.multipart } : {}),
+    };
+    const response = await page.context().request.fetch(`${this.backendBaseUrl}${path}`, requestOptions);
+    const text = await response.text();
+    if (!response.ok()) {
+      throw new Error(`${method} ${path} failed (${response.status()}): ${text || "no response body"}`);
+    }
+    return text ? JSON.parse(text) : {};
+  }
+
+  requireIdentity() {
+    if (!this.identity) {
+      throw new Error("UI sandbox identity has not been provisioned yet");
+    }
+    return this.identity;
+  }
+}
+
+function resolveFrontendBaseUrlFromTestInfo(testInfo, options = {}) {
+  const configured = typeof testInfo?.project?.use?.baseURL === "string" ? testInfo.project.use.baseURL : null;
+  return resolveFrontendBaseUrl({ ...options, frontendBaseUrl: options.frontendBaseUrl || configured || undefined });
+}
+
+function buildStableTestPrefix(testInfo) {
+  const title = Array.isArray(testInfo?.titlePath) ? testInfo.titlePath.join("-") : testInfo?.title || "ui";
+  return `${testInfo?.workerIndex ?? 0}-${testInfo?.retry ?? 0}-${title || "ui"}`;
+}
+
+function selectHomeOrganization(identity) {
+  const organizations = Array.isArray(identity.organizations) ? identity.organizations : [];
+  return (
+    organizations.find((organization) => organization.id && organization.id === identity.user?.homeOrganizationId) ||
+    organizations[0] ||
+    null
+  );
+}
+
+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(() => {});
+}
+
+export async function waitForAnimationFrames(page, frames = 2) {
+  const count = Math.max(1, Number(frames) || 1);
+  await page.evaluate(
+    (frameCount) =>
+      new Promise((resolve) => {
+        let remaining = frameCount;
+        const tick = () => {
+          remaining -= 1;
+          if (remaining <= 0) {
+            resolve();
+            return;
+          }
+          requestAnimationFrame(tick);
+        };
+        requestAnimationFrame(tick);
+      }),
+    count
+  );
+}
+
+function resolveBaseUrl(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("A UI base URL is required");
+  }
+  return assertSafeUiTarget(normalized);
+}
+
+function parseUrl(value) {
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+
+function isLocalHost(hostname) {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname.endsWith(".localhost")
+  );
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.118",
+  "version": "0.1.120",
   "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.118",
+  "version": "0.1.120",
   "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.118"
+    "@elench/testkit-protocol": "0.1.120"
   },
   "private": false
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.118",
+  "version": "0.1.120",
   "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.118",
+  "version": "0.1.120",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {