@cosmicdrift/kumiko-testing 0.295.0

package/src/e2e/seed-contract.ts

@@ -0,0 +1,85 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { z } from "zod";
+
+export const SEEDABLE_ROLES = [ROLES.TenantAdmin, ROLES.Member] as const;
+export const MAX_SEED_MEMBERS = 10;
+export const MAX_TENANT_NAME_LENGTH = 100;
+const MAX_EMAIL_LENGTH = 320;
+
+export const seedTenantRequestSchema = z.strictObject({
+  name: z.string().min(1).max(MAX_TENANT_NAME_LENGTH).optional(),
+  members: z.number().int().min(0).max(MAX_SEED_MEMBERS).optional(),
+});
+
+export const seededCredentialsSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  password: z.string(),
+});
+
+export const seedTenantResponseSchema = z.object({
+  id: z.string(),
+  key: z.string(),
+  name: z.string(),
+  admin: seededCredentialsSchema,
+  members: z.array(seededCredentialsSchema),
+});
+
+function isSystemAdminRole(role: string): boolean {
+  return role.trim().toLowerCase() === ROLES.SystemAdmin.toLowerCase();
+}
+
+export function resolveSeedableRoles(extraRoles: readonly string[] = []): readonly string[] {
+  for (const role of extraRoles) {
+    if (typeof role !== "string" || role.trim() === "") {
+      throw new Error(
+        `createE2eSeedRoutes: extraRoles entries must be non-empty strings, got ${JSON.stringify(role)}`,
+      );
+    }
+    if (isSystemAdminRole(role)) {
+      throw new Error(
+        `createE2eSeedRoutes: extraRoles must not contain ${ROLES.SystemAdmin}; it is never seedable`,
+      );
+    }
+  }
+  return [...new Set<string>([...SEEDABLE_ROLES, ...extraRoles])];
+}
+
+export function createSeedUserRequestSchema(extraRoles: readonly string[] = []) {
+  const seedable = resolveSeedableRoles(extraRoles);
+  return z.strictObject({
+    tenantId: z.uuid(),
+    roles: z
+      .array(
+        z.string().refine((role) => seedable.includes(role), {
+          message: `not a seedable role; allowed: ${seedable.join(", ")}`,
+        }),
+      )
+      .min(1)
+      .max(seedable.length),
+  });
+}
+
+export const seedUserRequestSchema = createSeedUserRequestSchema();
+
+export const seedUserResponseSchema = seededCredentialsSchema;
+
+export const inboxQuerySchema = z.strictObject({
+  tenantId: z.uuid(),
+  to: z.string().min(1).max(MAX_EMAIL_LENGTH),
+});
+
+const capturedMailSchema = z.object({
+  to: z.string(),
+  subject: z.string(),
+  html: z.string(),
+  from: z.string().optional(),
+  replyTo: z.string().optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const inboxResponseSchema = z.object({ messages: z.array(capturedMailSchema) });
+
+export type CapturedMail = z.infer<typeof capturedMailSchema>;
+export type SeedTenantResponse = z.infer<typeof seedTenantResponseSchema>;
+export type SeedUserRequest = z.infer<typeof seedUserRequestSchema>;

package/src/e2e/seed-route.ts

@@ -0,0 +1,135 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import {
+  getInbox,
+  mailTransportInMemoryFeature,
+} from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
+import { tenantTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import type { CreateKumikoServerOptions } from "@cosmicdrift/kumiko-dev-server";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { z } from "zod";
+import {
+  persistTenantRows,
+  persistUserRows,
+  type SeedWriter,
+  unwrapSavedRow,
+} from "../seed-tenant";
+import {
+  SEED_ENABLE_ENV,
+  SEED_ROUTE_PREFIX,
+  SEED_ROUTES,
+  SEED_TOKEN_ENV,
+  SEED_TOKEN_HEADER,
+} from "./constants";
+import {
+  createSeedUserRequestSchema,
+  inboxQuerySchema,
+  seedTenantRequestSchema,
+} from "./seed-contract";
+
+type ExtraRoutes = NonNullable<CreateKumikoServerOptions["extraRoutes"]>;
+
+type ParsedBody<T> =
+  | { readonly success: true; readonly data: T }
+  | { readonly success: false; readonly error: string };
+
+function parseWith<S extends z.ZodType>(schema: S, value: unknown): ParsedBody<z.infer<S>> {
+  const result = schema.safeParse(value);
+  if (result.success) return { success: true, data: result.data };
+  const error = result.error.issues
+    .map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`)
+    .join("; ");
+  return { success: false, error };
+}
+
+function parseJsonBody<S extends z.ZodType>(schema: S, raw: string): ParsedBody<z.infer<S>> {
+  if (raw.trim() === "") return parseWith(schema, {});
+  try {
+    return parseWith(schema, JSON.parse(raw));
+  } catch {
+    return { success: false, error: "body: invalid JSON" };
+  }
+}
+
+function seedingEnabled(): boolean {
+  return process.env[SEED_ENABLE_ENV] === "1" && process.env["NODE_ENV"] !== "production";
+}
+
+function digest(value: string): Buffer {
+  return createHash("sha256").update(value).digest();
+}
+
+function tokenMatches(expected: string, provided: string | undefined): boolean {
+  return provided !== undefined && timingSafeEqual(digest(expected), digest(provided));
+}
+
+export type E2eSeedRoutesOptions = {
+  readonly extraRoles?: readonly string[];
+};
+
+export function createE2eSeedRoutes(options: E2eSeedRoutesOptions = {}): ExtraRoutes {
+  const seedUserRequestSchema = createSeedUserRequestSchema(options.extraRoles);
+  return (app, deps) => {
+    const write: SeedWriter = async (handlerQn, payload, tenantId) =>
+      unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
+
+    app.use(`${SEED_ROUTE_PREFIX}/*`, async (c, next) => {
+      // c.notFound() would let the dev server answer unmatched GETs with its HTML shell (200).
+      if (!seedingEnabled()) return c.text("Not Found", 404);
+      const expected = process.env[SEED_TOKEN_ENV];
+      if (expected === undefined || expected === "") {
+        return c.json(
+          { error: `${SEED_TOKEN_ENV} is not set; refusing to serve seed routes` },
+          500,
+        );
+      }
+      if (!tokenMatches(expected, c.req.header(SEED_TOKEN_HEADER))) {
+        return c.json({ error: "invalid seed token" }, 401);
+      }
+      await next();
+    });
+
+    app.post(SEED_ROUTES.seedTenant, async (c) => {
+      const body = parseJsonBody(seedTenantRequestSchema, await c.req.text());
+      if (!body.success) return c.json({ error: body.error }, 400);
+      try {
+        return c.json(
+          await persistTenantRows(write, { name: body.data.name, users: body.data.members }),
+        );
+      } catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);
+      }
+    });
+
+    app.post(SEED_ROUTES.seedUser, async (c) => {
+      const body = parseJsonBody(seedUserRequestSchema, await c.req.text());
+      if (!body.success) return c.json({ error: body.error }, 400);
+      if ((await fetchOne(deps.db, tenantTable, { id: body.data.tenantId })) === undefined) {
+        return c.json({ error: `unknown tenant ${body.data.tenantId}` }, 404);
+      }
+      try {
+        return c.json(await persistUserRows(write, body.data.tenantId, body.data.roles));
+      } catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);
+      }
+    });
+
+    app.get(SEED_ROUTES.inbox, (c) => {
+      if (!deps.registry.features.has(mailTransportInMemoryFeature.name)) {
+        return c.json(
+          { error: `${mailTransportInMemoryFeature.name} is not mounted; no inbox to read` },
+          501,
+        );
+      }
+      const query = parseWith(inboxQuerySchema, {
+        tenantId: c.req.query("tenantId"),
+        to: c.req.query("to"),
+      });
+      if (!query.success) return c.json({ error: query.error }, 400);
+      const recipient = query.data.to.toLowerCase();
+      const messages = getInbox(query.data.tenantId).filter(
+        (message) => message.to.toLowerCase() === recipient,
+      );
+      return c.json({ messages });
+    });
+  };
+}

package/src/e2e/seeded-tenant-fixture.ts

@@ -0,0 +1,123 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { type APIRequestContext, test as base, type Page } from "@playwright/test";
+import type { z } from "zod";
+import {
+  type BoundApi,
+  type SeededCredentials,
+  type SeededTenant,
+  type SeededUser,
+  type SeedTenantOptions,
+  withSession,
+} from "../seed-types";
+import { createHttpApi, loginViaApi } from "./auth-kit";
+import { SEED_ROUTES } from "./constants";
+import { seedRouteHeaders } from "./mail-capture";
+import {
+  type SeedUserRequest,
+  seedTenantResponseSchema,
+  seedUserResponseSchema,
+} from "./seed-contract";
+
+export type E2eSeedTenantOptions = Omit<SeedTenantOptions, "persist">;
+
+export type E2eSeededTenant = SeededTenant & {
+  readonly loginAs: (page: Page, user: SeededUser) => Promise<void>;
+};
+
+type E2eFixtures = {
+  seedTenant: (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
+};
+
+async function postSeedRoute<S extends z.ZodType>(
+  request: APIRequestContext,
+  path: string,
+  body: Record<string, unknown>,
+  schema: S,
+): Promise<z.infer<S>> {
+  const response = await request.post(path, { headers: seedRouteHeaders(), data: body });
+  if (!response.ok()) {
+    throw new Error(`seedTenant: POST ${path} -> ${response.status()} ${await response.text()}`);
+  }
+  return schema.parse(await response.json());
+}
+
+export const test = base.extend<E2eFixtures>({
+  seedTenant: async ({ request, context, playwright, baseURL }, use) => {
+    if (baseURL === undefined) throw new Error("seedTenant: the Playwright config has no baseURL");
+    const openedContexts: APIRequestContext[] = [];
+    const apiByUserId = new Map<string, BoundApi>();
+
+    // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
+    const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
+      const ctx = await playwright.request.newContext({ baseURL });
+      openedContexts.push(ctx);
+      await loginViaApi(ctx, user);
+      return createHttpApi(ctx);
+    };
+
+    const httpApiFor = (user: SeededUser): BoundApi => {
+      const cached = apiByUserId.get(user.id);
+      if (cached !== undefined) return cached;
+      let opened: Promise<BoundApi> | undefined;
+      const bound = (): Promise<BoundApi> => {
+        opened ??= openLoggedInApi(user);
+        return opened;
+      };
+      const api: BoundApi = {
+        writeOk: async (type, payload, requestId) =>
+          (await bound()).writeOk(type, payload, requestId),
+        writeErr: async (type, payload) => (await bound()).writeErr(type, payload),
+        queryOk: async (type, payload) => (await bound()).queryOk(type, payload),
+        queryErr: async (type, payload) => (await bound()).queryErr(type, payload),
+      };
+      apiByUserId.set(user.id, api);
+      return api;
+    };
+
+    const loginAs = async (page: Page, user: SeededUser): Promise<void> => {
+      await page.context().clearCookies();
+      await loginViaApi(page.context().request, user);
+    };
+
+    await use(async (opts = {}) => {
+      const seeded = await postSeedRoute(
+        request,
+        SEED_ROUTES.seedTenant,
+        { name: opts.name, members: opts.users },
+        seedTenantResponseSchema,
+      );
+      const tenantId = seeded.id;
+      const toUser = (credentials: SeededCredentials, roles: readonly string[]): SeededUser =>
+        withSession(credentials, tenantId, roles);
+
+      const admin = toUser(seeded.admin, [ROLES.TenantAdmin]);
+      await loginViaApi(context.request, admin);
+
+      const tenant: E2eSeededTenant = {
+        id: tenantId,
+        key: seeded.key,
+        name: seeded.name,
+        admin,
+        members: seeded.members.map((member) => toUser(member, [ROLES.Member])),
+        addUser: async (roles = [ROLES.Member]) =>
+          toUser(
+            await postSeedRoute(
+              request,
+              SEED_ROUTES.seedUser,
+              { tenantId, roles: [...roles] } satisfies SeedUserRequest,
+              seedUserResponseSchema,
+            ),
+            roles,
+          ),
+        api: httpApiFor(admin),
+        apiAs: httpApiFor,
+        loginAs,
+      };
+
+      for (const part of opts.with ?? []) await part({ tenant });
+      return tenant;
+    });
+
+    await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
+  },
+});

package/src/e2e/timeouts.ts

@@ -0,0 +1,10 @@
+// Class budget for every app: solon's 30s/5s flows run 4-parallel today; webServer is the
+// slowest sample boot (Bun.build + Tailwind), poll is phronexsis's 15s projection wait.
+export const E2E_TIMEOUT_MS = {
+  test: 30_000,
+  expect: 5_000,
+  action: 5_000,
+  navigation: 10_000,
+  poll: 15_000,
+  webServer: 90_000,
+} as const;

package/src/index.ts

@@ -0,0 +1,18 @@
+export { PROVIDER_ENV_KEYS } from "./provider-env-keys";
+export {
+  type BoundApi,
+  type PersistedTenant,
+  persistTenantRows,
+  type SavedRow,
+  type SeededCredentials,
+  type SeededTenant,
+  type SeededUser,
+  type SeedPart,
+  type SeedTenantOptions,
+  type SeedWriter,
+  seedTenant,
+} from "./seed-tenant";
+export {
+  type SetupAppTestStackOptions,
+  setupAppTestStack,
+} from "./setup-app-test-stack";

package/src/integration-runner.ts

@@ -0,0 +1,37 @@
+import { BUNFIG_FILES, TEST_TIMEOUT_MS } from "./bunfig";
+
+export type IntegrationRunOptions = {
+  readonly files: readonly string[];
+  readonly parallel?: number;
+  readonly timings?: string;
+  readonly updateTimings?: boolean;
+};
+
+const EXCLUDED_SEGMENTS: ReadonlySet<string> = new Set(["node_modules", "dist", "e2e"]);
+
+export function selectIntegrationFiles(paths: readonly string[]): string[] {
+  return paths
+    .filter((path) => path.endsWith(".integration.test.ts"))
+    .filter((path) => !path.split("/").some((segment) => EXCLUDED_SEGMENTS.has(segment)))
+    .sort();
+}
+
+const isPositiveInteger = (value: number): boolean => Number.isInteger(value) && value > 0;
+
+export function buildIntegrationTestArgs(opts: IntegrationRunOptions): string[] {
+  if (opts.parallel !== undefined && !isPositiveInteger(opts.parallel)) {
+    throw new Error(`--parallel must be a positive integer, got ${opts.parallel}`);
+  }
+  if (opts.updateTimings === true && opts.timings === undefined) {
+    throw new Error("--update-timings needs --timings <file>");
+  }
+  return [
+    "test",
+    `--config=${BUNFIG_FILES.integration}`,
+    `--timeout=${TEST_TIMEOUT_MS.integration}`,
+    ...(opts.parallel !== undefined ? [`--parallel=${opts.parallel}`] : []),
+    ...(opts.timings !== undefined ? [`--timings=${opts.timings}`] : []),
+    ...(opts.updateTimings === true ? ["--update-timings"] : []),
+    ...opts.files,
+  ];
+}

package/src/preload/ci-log.ts

@@ -0,0 +1,2 @@
+// biome-ignore-all lint/suspicious/noConsole: the preload exists to print this line.
+console.log("[kumiko-test] CI profile active — config=bunfig.ci.toml concurrency=1");

package/src/preload/env.ts

@@ -0,0 +1,2 @@
+import "./scrub-env";
+import "./service-env-defaults";

package/src/preload/real.ts

@@ -0,0 +1,4 @@
+import { requireRealProviders } from "@cosmicdrift/kumiko-framework/testing";
+import "./service-env-defaults";
+
+requireRealProviders();

package/src/preload/scrub-env.ts

@@ -0,0 +1,3 @@
+import { scrubProviderEnv } from "../provider-env-keys";
+
+scrubProviderEnv(process.env);

package/src/preload/service-env-defaults.ts

@@ -0,0 +1,14 @@
+process.env["DATABASE_URL"] ??= "postgresql://kumiko:kumiko@localhost:15432/kumiko_dev";
+process.env["TEST_DATABASE_URL"] ??= "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
+process.env["REDIS_URL"] ??= "redis://localhost:16379";
+process.env["MEILI_URL"] ??= "http://localhost:17700";
+process.env["MEILI_MASTER_KEY"] ??= "kumiko-dev-key";
+process.env["JWT_SECRET"] ??= "test-jwt-secret-at-least-32-characters-long";
+
+process.env["MINIO_ENDPOINT"] ??= "http://localhost:19000";
+process.env["MINIO_ACCESS_KEY"] ??= "kumiko";
+process.env["MINIO_SECRET_KEY"] ??= "kumiko-dev-secret";
+process.env["MINIO_BUCKET"] ??= "kumiko-dev";
+process.env["MINIO_REGION"] ??= "us-east-1";
+
+process.env["LEGACY_DATABASE_URL"] ??= "";

package/src/preload/temporal.ts

@@ -0,0 +1,6 @@
+import { ensureTemporalPolyfill } from "@cosmicdrift/kumiko-framework/time";
+
+await ensureTemporalPolyfill();
+
+process.env["KUMIKO_INSTANCE_ID"] ??= "test-instance";
+process.env.NODE_ENV ??= "test";

package/src/provider-env-keys.ts

@@ -0,0 +1,16 @@
+export const PROVIDER_ENV_KEYS = [
+  "ANTHROPIC_API_KEY",
+  "STRIPE_API_KEY",
+  "STRIPE_WEBHOOK_SECRET",
+  "MOLLIE_API_KEY",
+  "SMTP_HOST",
+  "SMTP_USER",
+  "SMTP_PASS",
+  "S3_ACCESS_KEY",
+  "S3_SECRET_KEY",
+  "PLATFORM_KEK_KMS_TOKEN",
+] as const;
+
+export function scrubProviderEnv(env: Record<string, string | undefined>): void {
+  for (const key of PROVIDER_ENV_KEYS) delete env[key];
+}

package/src/scaffold.ts

@@ -0,0 +1,203 @@
+// @runtime tooling
+import { BUNFIG_FILES, renderBunfigFiles, TEST_TIMEOUT_MS } from "./bunfig";
+import { REAL_PROVIDERS_ENV } from "./e2e/constants";
+
+export type ScaffoldTestSetup = {
+  readonly files: Readonly<Record<string, string>>;
+  readonly scripts: Readonly<Record<string, string>>;
+  readonly devDependencies: Readonly<Record<string, string>>;
+  readonly rulesMarkdown: string;
+};
+
+export type RenderTestSetupInput = {
+  readonly appName: string;
+  readonly frameworkVersion: string;
+  readonly port?: number;
+};
+
+// One above the scaffold's `bun dev` default (4173) so both can run side by side.
+export const SCAFFOLD_E2E_PORT = 4174;
+
+export const SCAFFOLD_INTEGRATION_PARALLEL = 4;
+
+const PLAYWRIGHT_VERSION = "^1.62.1";
+
+const TEST_RUNTIME_DIRECTIVE = "// @runtime test";
+
+const TASK_CREATE = "tasks:write:task:create";
+const TASK_LIST = "tasks:query:task:list";
+
+const RULES_MARKDOWN = [
+  "## Testing",
+  "",
+  "- Three classes, told apart by file name: `*.test.ts` (unit, no services), `*.integration.test.ts` (real Postgres/Redis stack), `e2e/*.spec.ts` (Playwright against a booted app).",
+  "- Run them with `bun run test`, `bun run test:integration` and `bun run e2e`. Integration and e2e need `docker compose up -d` and a `.env` (copy `.env.example`).",
+  `- Real-provider tests only run with \`${REAL_PROVIDERS_ENV}=1\`, via \`bun run test:real\` / \`bun run e2e:real\`, locally and never in CI.`,
+  "- Tests run in parallel by default. Timeouts, retries and workers live in the scripts, the bunfig files and `playwright.config.ts`; never raise them inside a test. The only exception carries a marker: `// @timeout-exception: #<issue> <reason>`.",
+  "- Every flow seeds its own tenant: `seedTenant(stack)` in integration tests, the `seedTenant` fixture in e2e. No shared tenant, no widened seed helper.",
+  "- Red or flaky? Diagnose the cause first (`docs/guides/test-failures.md` in the kumiko-framework repo). A longer timeout, a retry or `serial` is not a fix.",
+  "- Run Playwright as `bunx --bun playwright`, as the scripts do.",
+  `- Playwright configs and e2e files start with \`${TEST_RUNTIME_DIRECTIVE}\`; without it the runtime-isolation guard flags their import of the test package.`,
+  "",
+].join("\n");
+
+function renderPlaywrightConfig(port: number): string {
+  return [
+    TEST_RUNTIME_DIRECTIVE,
+    'import { defineAppE2eConfig } from "@cosmicdrift/kumiko-testing/e2e";',
+    "",
+    `export default defineAppE2eConfig({ port: ${port} });`,
+    "",
+  ].join("\n");
+}
+
+function renderE2eServer(appName: string): string {
+  return [
+    TEST_RUNTIME_DIRECTIVE,
+    'import { randomUUID } from "node:crypto";',
+    'import { runDevApp } from "@cosmicdrift/kumiko-dev-server";',
+    'import { createE2eSeedRoutes } from "@cosmicdrift/kumiko-testing/e2e/seed-route";',
+    'import { APP_FEATURES } from "../src/run-config";',
+    "",
+    "await runDevApp({",
+    "  features: APP_FEATURES,",
+    '  clientEntry: "./src/client.tsx",',
+    "  extraRoutes: createE2eSeedRoutes(),",
+    "  auth: {",
+    "    admin: {",
+    `      email: ${JSON.stringify(`admin@${appName}.local`)},`,
+    "      password: randomUUID(),",
+    '      displayName: "Admin",',
+    "      emailVerified: true,",
+    "      memberships: [],",
+    "    },",
+    "  },",
+    "});",
+    "",
+  ].join("\n");
+}
+
+function renderE2eSmokeSpec(): string {
+  return [
+    TEST_RUNTIME_DIRECTIVE,
+    'import type { SeedPart } from "@cosmicdrift/kumiko-testing";',
+    'import { expect, test } from "@cosmicdrift/kumiko-testing/e2e";',
+    'import type { Page } from "@playwright/test";',
+    "",
+    `const TASK_CREATE = ${JSON.stringify(TASK_CREATE)};`,
+    "",
+    "function withTask(title: string): SeedPart {",
+    "  return async ({ tenant }) => {",
+    '    await tenant.api.writeOk(TASK_CREATE, { title, status: "todo", priority: 1 });',
+    "  };",
+    "}",
+    "",
+    "async function openTasks(page: Page): Promise<void> {",
+    '  await page.goto("/");',
+    '  await page.getByRole("link", { name: "Tasks" }).first().click();',
+    "}",
+    "",
+    'test("a seeded task shows up on the tasks screen", async ({ seedTenant, page }) => {',
+    '  const tenant = await seedTenant({ with: [withTask("Water the plants")] });',
+    "  await tenant.loginAs(page, tenant.admin);",
+    "  await openTasks(page);",
+    '  await expect(page.getByText("Water the plants")).toBeVisible();',
+    "});",
+    "",
+    'test("a task stays invisible to another tenant", async ({ seedTenant, page }) => {',
+    '  await seedTenant({ with: [withTask("Secret plans")] });',
+    '  const other = await seedTenant({ with: [withTask("Own task")] });',
+    "  await other.loginAs(page, other.admin);",
+    "  await openTasks(page);",
+    '  await expect(page.getByText("Own task")).toBeVisible();',
+    '  await expect(page.getByText("Secret plans")).toHaveCount(0);',
+    "});",
+    "",
+  ].join("\n");
+}
+
+function renderUnitTest(): string {
+  return [
+    'import { describe, expect, test } from "bun:test";',
+    'import { createRegistry, validateBoot } from "@cosmicdrift/kumiko-framework/engine";',
+    'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
+    'import { APP_FEATURES, HAS_AUTH } from "../run-config";',
+    "",
+    'describe("run-config", () => {',
+    '  test("the mounted features pass boot validation and register the task handlers", () => {',
+    "    const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
+    "    validateBoot(features);",
+    "    const registry = createRegistry(features);",
+    `    expect(registry.getWriteHandler(${JSON.stringify(TASK_CREATE)})).toBeDefined();`,
+    `    expect(registry.getQueryHandler(${JSON.stringify(TASK_LIST)})).toBeDefined();`,
+    "  });",
+    "});",
+    "",
+  ].join("\n");
+}
+
+function renderIntegrationTest(): string {
+  return [
+    'import { afterAll, beforeAll, describe, expect, test } from "bun:test";',
+    'import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";',
+    'import { seedTenant, setupAppTestStack } from "@cosmicdrift/kumiko-testing";',
+    'import { tasksFeature } from "../features/tasks";',
+    "",
+    `const TASK_CREATE = ${JSON.stringify(TASK_CREATE)};`,
+    `const TASK_LIST = ${JSON.stringify(TASK_LIST)};`,
+    "",
+    "type TaskList = { rows: { title: string }[] };",
+    "",
+    "let stack: TestStack;",
+    "",
+    "beforeAll(async () => {",
+    "  stack = await setupAppTestStack([tasksFeature]);",
+    "});",
+    "",
+    "afterAll(async () => {",
+    "  await stack.cleanup();",
+    "});",
+    "",
+    'describe("tasks", () => {',
+    '  test("a created task is listed for its own tenant only", async () => {',
+    "    const owner = await seedTenant(stack);",
+    "    const other = await seedTenant(stack);",
+    "",
+    '    await owner.api.writeOk(TASK_CREATE, { title: "Write tests", status: "todo", priority: 1 });',
+    "",
+    "    const ownerTasks = await owner.api.queryOk<TaskList>(TASK_LIST, {});",
+    '    expect(ownerTasks.rows.map((row) => row.title)).toEqual(["Write tests"]);',
+    "    const otherTasks = await other.api.queryOk<TaskList>(TASK_LIST, {});",
+    "    expect(otherTasks.rows).toEqual([]);",
+    "  });",
+    "});",
+    "",
+  ].join("\n");
+}
+
+export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup {
+  const { appName, frameworkVersion, port = SCAFFOLD_E2E_PORT } = input;
+  return {
+    files: {
+      ...renderBunfigFiles({ install: { linker: "hoisted" } }),
+      "playwright.config.ts": renderPlaywrightConfig(port),
+      "e2e/server.ts": renderE2eServer(appName),
+      "e2e/smoke.spec.ts": renderE2eSmokeSpec(),
+      "src/__tests__/run-config.test.ts": renderUnitTest(),
+      "src/__tests__/tasks.integration.test.ts": renderIntegrationTest(),
+    },
+    scripts: {
+      test: `bun --config=${BUNFIG_FILES.unit} test --timeout=${TEST_TIMEOUT_MS.unit} --dots`,
+      "test:integration": `bun kumiko-testing integration --parallel ${SCAFFOLD_INTEGRATION_PARALLEL}`,
+      "test:real": `${REAL_PROVIDERS_ENV}=1 bun --config=${BUNFIG_FILES.real} test --timeout=${TEST_TIMEOUT_MS.real}`,
+      "test:bunfig": "bun kumiko-testing bunfig --hoisted",
+      e2e: "bunx --bun playwright test",
+      "e2e:real": `${REAL_PROVIDERS_ENV}=1 bunx --bun playwright test`,
+    },
+    devDependencies: {
+      "@cosmicdrift/kumiko-testing": frameworkVersion,
+      "@playwright/test": PLAYWRIGHT_VERSION,
+    },
+    rulesMarkdown: RULES_MARKDOWN,
+  };
+}