@cosmicdrift/kumiko-framework 0.1.0

package/src/stack/test-stack.ts

@@ -0,0 +1,357 @@
+import type { Hono } from "hono";
+import type { AuthRoutesConfig } from "../api/auth-routes";
+import type { JwtHelper } from "../api/jwt";
+import { buildServer } from "../api/server";
+import { createSseBroker } from "../api/sse-broker";
+import type { DbConnection } from "../db/connection";
+import { createRegistry } from "../engine/registry";
+import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
+import { createArchivedStreamsTable, createEventsTable } from "../event-store";
+import type { Lifecycle } from "../lifecycle";
+import type { ObservabilityProvider } from "../observability";
+import type { EventDispatcher } from "../pipeline";
+import { createEntityCache, createEventDedup, createIdempotencyGuard } from "../pipeline";
+import { createInMemorySearchAdapter } from "../search";
+import type { SearchAdapter } from "../search/types";
+import { createTestDb } from "./db";
+import { createEventCollector, type EventCollector } from "./event-collector";
+import { createTestRedis, type TestRedis } from "./redis";
+import { createRequestHelper, type RequestHelper } from "./request-helper";
+import { pushTables } from "./table-helpers";
+
+export type TestStack = {
+  app: Hono;
+  jwt: JwtHelper;
+  registry: Registry;
+  /** Drizzle connection — the test DB's lifecycle (name, raw pg client,
+   *  drop) lives inside setupTestStack and is released via stack.cleanup(). */
+  db: DbConnection;
+  redis: TestRedis;
+  search: SearchAdapter;
+  events: EventCollector;
+  http: RequestHelper;
+  observability: ObservabilityProvider;
+  // Present whenever a system consumer (SSE, Search) or
+  // r.multiStreamProjection is wired. Tests drain it via runOnce() for
+  // deterministic assertion — no timer-induced flakiness.
+  eventDispatcher?: EventDispatcher;
+  // Only set when the caller passed `lifecycle` via options. Tests that
+  // exercise drain() / /health/ready wire one in; ordinary suites ignore it.
+  lifecycle?: Lifecycle;
+  cleanup: () => Promise<void>;
+};
+
+export type TestStackOptions = {
+  features: readonly FeatureDefinition[];
+  /** System hooks to wire up. Default: all (sse, search) */
+  systemHooks?: ("sse" | "search")[];
+  /** Search config per tenant — defaults to tenant 1 with all text fields */
+  searchConfig?: {
+    tenantId: TenantId;
+    searchableFields: string[];
+    rankingFields: string[];
+  };
+  jwtSecret?: string;
+  /** Extra fields merged into the AppContext (e.g. _notifyFactory, configResolver).
+   *  Can be a function receiving (registry, db, sseBroker) for late binding. */
+  extraContext?:
+    | Record<string, unknown>
+    | ((deps: {
+        registry: Registry;
+        db: import("../db/connection").DbConnection;
+        sseBroker: import("../api/sse-broker").SseBroker;
+        redis: import("ioredis").default;
+      }) => Record<string, unknown>);
+  /** Wire up auth routes (login, tenant-switch). Leave undefined to skip. */
+  authConfig?: AuthRoutesConfig;
+  /** Register a file storage provider so uploads via POST /api/files work and
+   *  `ctx.files.ref(key)` is available to hooks/MSPs. Omit to skip — tests
+   *  without file handling don't need it. */
+  files?: { storageProvider: import("../files").FileStorageProvider };
+  /** Observability provider — omit for NoopProvider (no spans/metrics).
+   *  Pass a ConsoleProvider to see the span tree in stdout, or a custom
+   *  provider (e.g. a recording provider for assertions in tests). */
+  observability?: ObservabilityProvider;
+  /** Inject a process lifecycle so tests can drain() and observe
+   *  /health/ready flipping to 503. Omit if the suite doesn't care. */
+  lifecycle?: Lifecycle;
+  /** Wire L1 (global-IP) and/or L2 (auth-endpoint) rate-limit middleware.
+   *  The resolver is auto-built from the test Redis. Mirrors
+   *  buildServer's `rateLimit` option 1:1 — see there for shape. */
+  rateLimit?: import("../api/server").ServerOptions["rateLimit"];
+  /** Inject a MasterKeyProvider for secrets-backed tests. Lands typed in
+   *  AppContext — set/delete/get + rotation job pick it up. Omit for
+   *  suites that don't touch secrets. */
+  masterKeyProvider?: import("../secrets").MasterKeyProvider;
+  /** Feature-toggle resolver. When present the dispatcher's feature-gate,
+   *  hook-filter, and MSP-filter all consult it; absent = every feature
+   *  treated as always-on. Pass the callback from
+   *  GlobalFeatureToggleRuntime.effectiveFeatures for real DB-backed
+   *  toggles, or a plain `() => new Set<string>(registry.features.keys())`
+   *  to force a specific snapshot in a unit-style setup. */
+  effectiveFeatures?: () => ReadonlySet<string>;
+  /** Pin the underlying Postgres DB name instead of the default
+   *  `kumiko_test_<8chars>`. Forwarded to createTestDb. Primary use
+   *  case: dev servers that want persistent storage across restarts —
+   *  combine with `persistentDb: true`. */
+  dbName?: string;
+  /** When true, cleanup() keeps the Postgres DB around — the caller
+   *  owns its lifecycle. Default false (test contract). Used by
+   *  dev-server wiring to survive hot-reloads. */
+  persistentDb?: boolean;
+  /** Forwarded to buildServer — when set, requests without a JWT pass
+   *  through as anonymous instead of 401. See AnonymousAccessConfig.
+   *  Akzeptiert entweder einen statischen Config-Object ODER eine Factory
+   *  `({registry, db, sseBroker, redis}) => Config` — gleiches Pattern wie
+   *  `extraContext`. Die Factory wird einmal beim Boot aufgerufen, der
+   *  TenantResolver darin closure'd typischerweise `db` für Subdomain-
+   *  Lookups. */
+  anonymousAccess?:
+    | import("../api/server").ServerOptions["anonymousAccess"]
+    | ((deps: {
+        registry: Registry;
+        db: import("../db/connection").DbConnection;
+        sseBroker: import("../api/sse-broker").SseBroker;
+        redis: import("ioredis").default;
+      }) => import("../api/server").ServerOptions["anonymousAccess"]);
+};
+
+const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
+
+export async function setupTestStack(options: TestStackOptions): Promise<TestStack> {
+  const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
+  const enabledHooks = options.systemHooks ?? ["sse", "search"];
+
+  // Temporal-Polyfill installieren bevor Feature-Code läuft. Idempotent —
+  // Production-Server-Boot ruft das gleich. Auf Runtimes mit nativem
+  // Temporal ein No-Op.
+  const { ensureTemporalPolyfill } = await import("../time/polyfill");
+  await ensureTemporalPolyfill();
+
+  // Forward db-name/persistent-flag through to createTestDb. The
+  // defaults (undefined dbName, persistent:false) keep the legacy
+  // test contract: fresh kumiko_test_<random> DB per setup, dropped
+  // on cleanup.
+  const [testDb, testRedis] = await Promise.all([
+    createTestDb({
+      ...(options.dbName !== undefined && { dbName: options.dbName }),
+      ...(options.persistentDb !== undefined && { persistent: options.persistentDb }),
+    }),
+    createTestRedis(),
+  ]);
+
+  // Every ES-entity writes events via createEventStoreExecutor in the
+  // feature's write handlers. Auto-create the events table so every
+  // setupTestStack call is ready for writes without needing a manual
+  // createEventsTable().
+  await createEventsTable(testDb.db);
+  // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
+  // loadAggregate's default-skip. Idempotent, so production boot running
+  // the same call is fine.
+  await createArchivedStreamsTable(testDb.db);
+
+  // Framework state for projection rebuild/status + event-consumer cursors.
+  // Idempotent — production boot flows run the same calls.
+  const { createProjectionStateTable, createEventConsumerStateTable } = await import("../pipeline");
+  await createProjectionStateTable(testDb.db);
+  await createEventConsumerStateTable(testDb.db);
+
+  // Files support: when a provider is registered, the fileRefs table must
+  // exist before the first upload. Skipped when no provider — the table
+  // stays off tenant test DBs that never touch files.
+  if (options.files) {
+    const { fileRefsTable } = await import("../files");
+    await pushTables(testDb.db, { fileRefsTable });
+  }
+
+  // Projection tables: the executor writes into them in the same TX as the
+  // event-append, so they have to exist before the first write. Auto-push
+  // everything registered via r.projection() — keeps tests from having to
+  // know which projections a feature happens to declare. Two projections
+  // backed by the same physical table (e.g. an alternative apply-shape for
+  // the same read-model in a test feature) are deduped by Drizzle-table
+  // reference so drizzle-kit doesn't emit duplicate CREATE TABLE statements.
+  const projectionTables: Record<string, unknown> = {};
+  const seenTables = new Set<unknown>();
+  for (const feature of options.features) {
+    for (const [projName, proj] of Object.entries(feature.projections)) {
+      if (seenTables.has(proj.table)) continue;
+      seenTables.add(proj.table);
+      projectionTables[projName] = proj.table;
+    }
+    // Multi-stream projection tables follow the same auto-push rule — the
+    // async dispatcher writes to them as soon as the first matching event
+    // flows through, so the DDL must exist before setupTestStack returns.
+    // skip: MSPs without a table are pure side-effect consumers.
+    for (const [mspName, msp] of Object.entries(feature.multiStreamProjections)) {
+      if (!msp.table) continue;
+      if (seenTables.has(msp.table)) continue;
+      seenTables.add(msp.table);
+      projectionTables[`msp_${mspName}`] = msp.table;
+    }
+  }
+  if (Object.keys(projectionTables).length > 0) {
+    // pushTables emits raw CREATE TABLE — fine for ephemeral test DBs but
+    // collides on re-boot against a persistent DB whose projection tables
+    // were created during a previous run. Filter out the ones that already
+    // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
+    // them again.
+    const { tableExists } = await import("../db/schema-inspection");
+    const { getTableName } = await import("drizzle-orm");
+    const missing: Record<string, unknown> = {};
+    for (const [key, tbl] of Object.entries(projectionTables)) {
+      const physical = getTableName(tbl as Parameters<typeof getTableName>[0]);
+      if (await tableExists(testDb.db, `public.${physical}`)) continue;
+      missing[key] = tbl;
+    }
+    if (Object.keys(missing).length > 0) {
+      await pushTables(testDb.db, missing);
+    }
+  }
+
+  const searchAdapter = createInMemorySearchAdapter();
+  const events = createEventCollector();
+  const registry = createRegistry([...options.features]);
+
+  // Auto-configure search for tenant 1 based on registry
+  if (enabledHooks.includes("search")) {
+    const searchableFields: string[] = [];
+    for (const feature of options.features) {
+      for (const [, entity] of Object.entries(feature.entities)) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+          if (field.type === "text" && field.searchable) {
+            searchableFields.push(fieldName);
+          }
+          if (field.type === "embedded") {
+            for (const [subName, subField] of Object.entries(field.schema)) {
+              if (subField.searchable) {
+                searchableFields.push(`${fieldName}_${subName}`);
+              }
+            }
+          }
+        }
+      }
+    }
+
+    if (options.searchConfig) {
+      await searchAdapter.configure(options.searchConfig.tenantId, {
+        searchableFields: options.searchConfig.searchableFields,
+        rankingFields: options.searchConfig.rankingFields,
+      });
+    } else if (searchableFields.length > 0) {
+      await searchAdapter.configure("00000000-0000-4000-8000-000000000001", {
+        searchableFields,
+        rankingFields: searchableFields,
+      });
+    }
+  }
+
+  // Wire SSE broker with event collector
+  const sseBroker = createSseBroker();
+  sseBroker.addClient(
+    "tenant:00000000-0000-4000-8000-000000000001",
+    (event) => events.sse.push(event),
+    () => {},
+  );
+
+  const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
+  const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
+  const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
+
+  const server = buildServer({
+    registry,
+    context: {
+      db: testDb.db,
+      redis: testRedis.redis,
+      searchAdapter,
+      entityCache,
+      registry,
+      ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
+      ...(typeof options.extraContext === "function"
+        ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
+        : options.extraContext),
+    },
+    jwtSecret,
+    dispatcherOptions: {
+      idempotency,
+      ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
+    },
+    eventDedup,
+    sseBroker,
+    // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
+    // deterministic drains — no timer-induced flakiness. pollIntervalMs
+    // stays short anyway in case a test opts into `.start()`. pgClient
+    // plumbs through the LISTEN wake-up for tests that want to measure
+    // post-commit latency (Sprint E.4).
+    eventDispatcher: {
+      pollIntervalMs: 50,
+      pgClient: testDb.client,
+      systemConsumers: {
+        sse: enabledHooks.includes("sse"),
+        search: enabledHooks.includes("search"),
+      },
+    },
+    // Default tests to no login rate-limiter so existing suites that loop
+    // over logins don't hit a 429 after 10 attempts. Suites specifically
+    // testing the limiter can override via authConfig.loginRateLimit.
+    ...(options.authConfig
+      ? {
+          auth: {
+            ...options.authConfig,
+            ...(options.authConfig.loginRateLimit === undefined ? { loginRateLimit: null } : {}),
+          },
+        }
+      : {}),
+    ...(options.observability ? { observability: options.observability } : {}),
+    ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
+    ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
+    ...(options.anonymousAccess
+      ? {
+          anonymousAccess:
+            typeof options.anonymousAccess === "function"
+              ? options.anonymousAccess({
+                  registry,
+                  db: testDb.db,
+                  sseBroker,
+                  redis: testRedis.redis,
+                })
+              : options.anonymousAccess,
+        }
+      : {}),
+    // Wire the upload routes + ctx.files only when the caller registered a
+    // provider. Tests that don't touch files skip both without extra setup.
+    ...(options.files
+      ? { files: { db: testDb.db, storageProvider: options.files.storageProvider } }
+      : {}),
+  });
+
+  const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
+
+  // Pre-register consumer state rows so tests can call runOnce() directly
+  // without a preceding explicit start(). Timer fires at pollIntervalMs=50
+  // but passInFlight serialises concurrent passes — tests that drain via
+  // runOnce() remain deterministic. Tests that specifically exercise the
+  // timer loop call start() again (idempotent) after setup.
+  if (eventDispatcher) await eventDispatcher.ensureRegistered();
+
+  const http = createRequestHelper(server.app, server.jwt);
+
+  return {
+    app: server.app,
+    jwt: server.jwt,
+    registry,
+    db: testDb.db,
+    redis: testRedis,
+    search: searchAdapter,
+    events,
+    http,
+    observability: server.observability,
+    ...(eventDispatcher ? { eventDispatcher } : {}),
+    ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
+    cleanup: async () => {
+      if (eventDispatcher) await eventDispatcher.stop();
+      await server.observability.shutdown();
+      await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
+    },
+  };
+}

package/src/stack/test-users.ts

@@ -0,0 +1,37 @@
+import type { SessionUser, TenantId } from "../engine/types";
+
+// Zero-padded UUIDs used across the test suite. `testTenantId(1)` /
+// `testUserId(1)` read cleaner in assertions than the full UUID literals,
+// and keep all tests on a single shape — if the UUID layout ever changes,
+// it changes here.
+export function testTenantId(n: number): TenantId {
+  return `00000000-0000-4000-8000-${n.toString().padStart(12, "0")}`;
+}
+
+// Distinct prefix from tenantId so debug output visibly differentiates the
+// two when a user-id accidentally lands in a tenant-id slot.
+export function testUserId(n: number): string {
+  return `11111111-0000-4000-8000-${n.toString().padStart(12, "0")}`;
+}
+
+export const TestUsers = {
+  admin: { id: testUserId(1), tenantId: testTenantId(1), roles: ["Admin"] },
+  systemAdmin: { id: testUserId(1), tenantId: testTenantId(1), roles: ["SystemAdmin"] },
+  user: { id: testUserId(2), tenantId: testTenantId(1), roles: ["User"] },
+  driver: { id: testUserId(3), tenantId: testTenantId(1), roles: ["Driver"] },
+  otherTenant: { id: testUserId(10), tenantId: testTenantId(2), roles: ["Admin"] },
+} as const satisfies Record<string, SessionUser>;
+
+// Accept numeric shortcuts for legacy call sites — stringify to a UUID so the
+// SessionUser type stays aligned. `createTestUser({ id: 42 })` gives you
+// `testUserId(42)`. Explicit strings pass through untouched.
+export function createTestUser(
+  overrides?: Partial<Omit<SessionUser, "id">> & { id?: string | number },
+): SessionUser {
+  const normalizedId =
+    typeof overrides?.id === "number"
+      ? testUserId(overrides.id)
+      : (overrides?.id ?? TestUsers.admin.id);
+  const { id: _id, ...rest } = overrides ?? {};
+  return { ...TestUsers.admin, ...rest, id: normalizedId };
+}

package/src/testing/__tests__/e2e-generator.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import {
+  createBooleanField,
+  createEntity,
+  createRegistry,
+  createSelectField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../../engine";
+import { generateE2ESpec, generateZodFixture } from "../e2e-generator";
+
+const taskEntity = createEntity({
+  table: "tasks",
+  fields: {
+    title: createTextField({ required: true, maxLength: 200 }),
+    done: createBooleanField({ default: false }),
+    status: createSelectField({ options: ["todo", "doing", "done"] as const }),
+  },
+});
+
+// Minimal-Feature mit beiden Screen-Typen UND einem Create-Handler —
+// abhängig davon was im Screen steht, emittiert der Generator andere
+// Kind-Kombinationen, siehe buildListSpecs/buildEditSpecs.
+function createTasksFeature() {
+  return defineFeature("tasks", (r) => {
+    r.systemScope();
+    r.entity("task", taskEntity);
+    r.writeHandler(defineEntityCreateHandler("task", taskEntity));
+    r.screen({
+      id: "task-list",
+      type: "entityList",
+      entity: "task",
+      columns: ["title", "status", "done"],
+    });
+    r.screen({
+      id: "task-edit",
+      type: "entityEdit",
+      entity: "task",
+      layout: {
+        sections: [{ title: "tasks:section.basics", fields: ["title", "status", "done"] }],
+      },
+    });
+  });
+}
+
+describe("generateE2ESpec", () => {
+  test("emits list-renders + list-has-fixture-row for entityList screens", () => {
+    const registry = createRegistry([createTasksFeature()]);
+    const specs = generateE2ESpec(registry);
+
+    const listSpecs = specs.filter((s) => s.screenQn === "tasks:screen:task-list");
+    expect(listSpecs.map((s) => s.kind)).toEqual(["list-renders", "list-has-fixture-row"]);
+
+    const fixtureSpec = listSpecs.find((s) => s.kind === "list-has-fixture-row");
+    if (fixtureSpec?.kind !== "list-has-fixture-row") throw new Error("unreachable");
+    expect(fixtureSpec.writeHandlerQn).toBe("tasks:write:task:create");
+    expect(fixtureSpec.urlPath).toBe("/t/{tenant}/tasks/task-list");
+    expect(fixtureSpec.fixture["title"]).toBe("e2e title");
+    expect(fixtureSpec.identifyingValue).toBe("e2e title");
+  });
+
+  test("emits edit-validates-required + edit-save-persists for entityEdit screens", () => {
+    const registry = createRegistry([createTasksFeature()]);
+    const specs = generateE2ESpec(registry);
+
+    const editSpecs = specs.filter((s) => s.screenQn === "tasks:screen:task-edit");
+    expect(editSpecs.map((s) => s.kind)).toEqual(["edit-validates-required", "edit-save-persists"]);
+
+    const validates = editSpecs.find((s) => s.kind === "edit-validates-required");
+    if (validates?.kind !== "edit-validates-required") throw new Error("unreachable");
+    expect(validates.requiredFields).toEqual(["title"]);
+
+    const persists = editSpecs.find((s) => s.kind === "edit-save-persists");
+    if (persists?.kind !== "edit-save-persists") throw new Error("unreachable");
+    expect(persists.listUrlPath).toBe("/t/{tenant}/tasks/task-list");
+    expect(persists.identifyingField).toBe("title");
+    // Select-Field muss "select" bekommen, Boolean "check", Text "fill" —
+    // sonst emittiert der Renderer .fill() für ein Dropdown und Playwright
+    // zerschellt am ersten Sample mit Select-Feld.
+    expect(persists.fills).toEqual([
+      { kind: "fill", field: "title", value: "e2e title" },
+      { kind: "select", field: "status", value: "todo" },
+      { kind: "check", field: "done", value: true },
+    ]);
+  });
+
+  test("accepts tenant-slug override", () => {
+    const registry = createRegistry([createTasksFeature()]);
+    const specs = generateE2ESpec(registry, { tenantPlaceholder: "acme" });
+    expect(specs[0]?.urlPath).toMatch(/^\/t\/acme\//);
+  });
+
+  test("skips custom screens", () => {
+    const feature = defineFeature("audit", (r) => {
+      r.systemScope();
+      r.screen({
+        id: "log",
+        type: "custom",
+        renderer: { react: { __component: "X" } },
+      });
+    });
+    const specs = generateE2ESpec(createRegistry([feature]));
+    expect(specs).toEqual([]);
+  });
+
+  test("skips list-has-fixture-row when no create-handler is registered", () => {
+    // Feature hat Screen + Entity aber keinen Create-Handler (z.B. weil
+    // Writes noch in einer anderen Feature-Variante landen). Ohne Handler
+    // kann der Generator nicht seeden — list-renders bleibt, der Fixture-
+    // Test wird gespart statt falsch generiert.
+    const readOnly = defineFeature("read-only", (r) => {
+      r.systemScope();
+      r.entity("task", taskEntity);
+      r.screen({ id: "list", type: "entityList", entity: "task", columns: ["title"] });
+    });
+    const specs = generateE2ESpec(createRegistry([readOnly]));
+    expect(specs.map((s) => s.kind)).toEqual(["list-renders"]);
+  });
+
+  test("edit-save-persists has undefined listUrlPath when no matching list-screen exists", () => {
+    // entityEdit ohne entityList — z.B. Detail-Seite die über SSE Refresh
+    // statt Navigation validiert wird. Der Generator muss trotzdem eine
+    // edit-save-persists-Spec emittieren, nur ohne listUrlPath (Renderer
+    // verifiziert dann im Edit-View selbst).
+    const editOnly = defineFeature("edit-only", (r) => {
+      r.systemScope();
+      r.entity("task", taskEntity);
+      r.writeHandler(defineEntityCreateHandler("task", taskEntity));
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "task",
+        layout: { sections: [{ title: "s", fields: ["title"] }] },
+      });
+    });
+    const specs = generateE2ESpec(createRegistry([editOnly]));
+    const persists = specs.find((s) => s.kind === "edit-save-persists");
+    if (persists?.kind !== "edit-save-persists") throw new Error("unreachable");
+    expect(persists.listUrlPath).toBeUndefined();
+  });
+
+  test("text-field formats (email/url) produce format-specific fixtures", () => {
+    // createTextField({ format: "email" }) muss einen Mail-artigen Fixture
+    // liefern — sonst schlägt die Zod-Validation am Server fehl, sobald
+    // der Generator-Output gegen eine echte API läuft.
+    const contactEntity = createEntity({
+      table: "contacts",
+      fields: {
+        name: createTextField({ required: true }),
+        email: createTextField({ required: true, format: "email" }),
+        homepage: createTextField({ format: "url" }),
+      },
+    });
+    const feature = defineFeature("contacts", (r) => {
+      r.systemScope();
+      r.entity("contact", contactEntity);
+      r.writeHandler(defineEntityCreateHandler("contact", contactEntity));
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "contact",
+        columns: ["name", "email", "homepage"],
+      });
+    });
+    const specs = generateE2ESpec(createRegistry([feature]));
+    const fixtureSpec = specs.find((s) => s.kind === "list-has-fixture-row");
+    if (fixtureSpec?.kind !== "list-has-fixture-row") throw new Error("unreachable");
+    expect(fixtureSpec.fixture["email"]).toMatch(/^e2e-email@/);
+    expect(fixtureSpec.fixture["homepage"]).toBe("https://example.com");
+  });
+
+  test("mixed feature (list + edit + custom) — generates for list/edit, skips custom", () => {
+    // Deckt das Shape ab das ein echtes Sample hat: ein Feature mit allen
+    // drei Screen-Typen. Custom wird übersprungen, List + Edit liefern
+    // ihre jeweiligen Spec-Kinds.
+    const mixed = defineFeature("mixed", (r) => {
+      r.systemScope();
+      r.entity("task", taskEntity);
+      r.writeHandler(defineEntityCreateHandler("task", taskEntity));
+      r.screen({ id: "list", type: "entityList", entity: "task", columns: ["title"] });
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "task",
+        layout: { sections: [{ title: "mixed:s", fields: ["title"] }] },
+      });
+      r.screen({
+        id: "dashboard",
+        type: "custom",
+        renderer: { react: { __component: "X" } },
+      });
+    });
+    const specs = generateE2ESpec(createRegistry([mixed]));
+    const screens = new Set(specs.map((s) => s.screenQn));
+    expect(screens).toEqual(new Set(["mixed:screen:list", "mixed:screen:edit"]));
+    expect(specs.map((s) => s.kind).sort()).toEqual([
+      "edit-save-persists",
+      "edit-validates-required",
+      "list-has-fixture-row",
+      "list-renders",
+    ]);
+  });
+});
+
+describe("generateZodFixture", () => {
+  test("primitives", () => {
+    expect(generateZodFixture(z.string())).toBe("e2e-fixture");
+    expect(generateZodFixture(z.number())).toBe(1);
+    expect(generateZodFixture(z.boolean())).toBe(true);
+    expect(generateZodFixture(z.enum(["a", "b"]))).toBe("a");
+  });
+
+  test("string formats", () => {
+    expect(generateZodFixture(z.email())).toBe("e2e@example.com");
+    expect(generateZodFixture(z.url())).toBe("https://example.com");
+    expect(generateZodFixture(z.uuid())).toBe("00000000-0000-4000-8000-000000000000");
+  });
+
+  test("optional + default unwrap", () => {
+    expect(generateZodFixture(z.string().optional())).toBe("e2e-fixture");
+    expect(generateZodFixture(z.number().default(42))).toBe(1);
+  });
+
+  test("unsupported types throw", () => {
+    expect(() => generateZodFixture(z.object({}))).toThrow(/not supported yet/);
+    expect(() => generateZodFixture(z.array(z.string()))).toThrow(/not supported yet/);
+  });
+});

package/src/testing/__tests__/ensure-entity-table.integration.ts

@@ -0,0 +1,54 @@
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import type { EntityDefinition } from "../../engine/types";
+import { createEntityTable, createTestDb, ensureEntityTable, type TestDb } from "../../stack";
+
+// ensureEntityTable ist die idempotente Variante von createEntityTable —
+// existiert wegen des dev-server-Boot-Pfads (persistente DB, Table von
+// letztem Run). createEntityTable bleibt strict, damit Tests ein
+// falsches Schema nicht stillschweigend akzeptieren.
+
+const tenantEntity: EntityDefinition = {
+  fields: {
+    title: { type: "text", required: true },
+  },
+  table: "ensure_entity_table_probe",
+} as unknown as EntityDefinition;
+
+let db: TestDb;
+
+beforeAll(async () => {
+  db = await createTestDb();
+});
+
+afterAll(async () => {
+  await db.cleanup();
+});
+
+describe("ensureEntityTable", () => {
+  test("legt die Tabelle beim ersten Aufruf an (returnt true)", async () => {
+    const created = await ensureEntityTable(db.db, tenantEntity, "probe");
+    expect(created).toBe(true);
+    const rows = await db.db.execute<{ exists: boolean }>(
+      sql`SELECT to_regclass('public.ensure_entity_table_probe') IS NOT NULL AS exists`,
+    );
+    expect(rows[0]?.exists).toBe(true);
+  });
+
+  test("ist beim zweiten Aufruf ein No-Op (returnt false, kein Fehler)", async () => {
+    const created = await ensureEntityTable(db.db, tenantEntity, "probe");
+    expect(created).toBe(false);
+  });
+
+  test("createEntityTable bleibt strict — wirft bei existierender Tabelle", async () => {
+    // Gleiche Entity zweimal via createEntityTable → postgres 42P07
+    // (relation already exists). Drizzle wrappt den PG-Error in
+    // DrizzleQueryError; der echte Code steckt in .cause. Sicherstellt,
+    // dass ensureEntityTable nicht versehentlich das strict-Verhalten
+    // verändert.
+    await expect(createEntityTable(db.db, tenantEntity, "probe")).rejects.toSatisfy((err) => {
+      const cause = (err as { cause?: { code?: string } }).cause;
+      return cause?.code === "42P07";
+    });
+  });
+});