@elench/testkit 0.1.119 → 0.1.121

package/lib/ui/index.d.ts

@@ -27,6 +27,39 @@ export declare function createUiSandbox(options?: UiSandboxOptions): {
     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;
@@ -47,3 +80,42 @@ 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

@@ -4,6 +4,7 @@ export {
   assertSafeUiTarget,
   assertSafeUiTargets,
   createAuthedApiClient,
+  createProvisionedUiSandbox,
   createSandboxId,
   createUiSandbox,
   resolveBackendBaseUrl,
@@ -11,3 +12,12 @@ export {
   waitForAnimationFrames,
   waitForUiSettled,
 } from "./sandbox.mjs";
+export {
+  expectAuthenticatedShell,
+  loginAsProvisioned,
+  loginAsUiProfile,
+  loginWithCredentials,
+  persistUiSessionStorage,
+  provisionUiIdentity,
+  readUiConfig,
+} from "./provisioning.mjs";

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

@@ -17,6 +17,33 @@ export function createUiSandbox(options = {}) {
   };
 }
 
+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";
@@ -62,6 +89,125 @@ export async function createAuthedApiClient(playwrightRequest = request, options
   });
 }
 
+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,
+          loginWithCredentials,
+          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 loginWithCredentials(
+            page,
+            this.identity.credentials.email,
+            this.identity.credentials.password,
+            {
+              ...this.options,
+              frontendBaseUrl: this.frontendBaseUrl,
+            }
+          );
+        } else {
+          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 });

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.119",
+  "version": "0.1.121",
   "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.119",
+  "version": "0.1.121",
   "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.119",
+  "version": "0.1.121",
   "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.119",
-    "@elench/testkit-bridge": "0.1.119",
-    "@elench/testkit-protocol": "0.1.119",
-    "@elench/ts-analysis": "0.1.119",
+    "@elench/next-analysis": "0.1.121",
+    "@elench/testkit-bridge": "0.1.121",
+    "@elench/testkit-protocol": "0.1.121",
+    "@elench/ts-analysis": "0.1.121",
     "@oclif/core": "^4.10.6",
     "@playwright/test": "^1.52.0",
     "esbuild": "^0.25.11",