@mandujs/ate 0.17.3 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/ate",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "description": "Mandu ATE (Automation Test Engine) - extract/generate/run/report/heal/impact in one package",
   "type": "module",
   "sideEffects": false,

package/src/codegen.ts

@@ -2,16 +2,21 @@ import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { getAtePaths, ensureDir, readJson, writeJson } from "./fs";
 import type { ScenarioBundle } from "./scenario";
-import type { OracleLevel } from "./types";
+import type { InteractionEdge, InteractionGraph, InteractionNode, OracleLevel } from "./types";
 import { readSelectorMap, buildPlaywrightLocatorChain } from "./selector-map";
-import { generateL1Assertions } from "./oracle";
+import { generateL1Assertions, generateL2Assertions, generateL3Assertions } from "./oracle";
 import { detectDomain } from "./domain-detector";
 
 function specHeader(): string {
   return `import { test, expect } from "@playwright/test";\n\n`;
 }
 
-function oracleTemplate(level: OracleLevel, routePath: string): { setup: string; assertions: string } {
+function oracleTemplate(
+  level: OracleLevel,
+  routePath: string,
+  node?: InteractionNode,
+  edges?: InteractionEdge[],
+): { setup: string; assertions: string } {
   const setup: string[] = [];
   const assertions: string[] = [];
 
@@ -22,17 +27,16 @@ function oracleTemplate(level: OracleLevel, routePath: string): { setup: string;
   setup.push(`page.on("pageerror", (err) => errors.push(String(err)));`);
 
   if (level === "L1" || level === "L2" || level === "L3") {
-    // Use domain-aware L1 assertions
     const domain = detectDomain(routePath).domain;
     const l1Assertions = generateL1Assertions(domain, routePath);
     assertions.push(...l1Assertions);
   }
-  if (level === "L2" || level === "L3") {
-    assertions.push(`// L2: behavior signals (placeholder - extend per app)`);
-    assertions.push(`await expect(page).toHaveURL(/.*/);`);
+  if ((level === "L2" || level === "L3") && node) {
+    assertions.push(...generateL2Assertions(node));
   }
-  if (level === "L3") {
-    assertions.push(`// L3: domain hints (placeholder)`);
+  if (level === "L3" && node) {
+    const nodeEdges = (edges ?? []).filter(e => "from" in e && e.from === (node.kind === "route" ? node.path : ""));
+    assertions.push(...generateL3Assertions(node, nodeEdges));
   }
 
   assertions.push(`expect(errors, "console/page errors").toEqual([]);`);
@@ -56,6 +60,14 @@ export function generatePlaywrightSpecs(repoRoot: string, opts?: { onlyRoutes?:
     return { files: [], warnings };
   }
 
+  // Load interaction graph for L2/L3 node metadata
+  let graph: InteractionGraph | undefined;
+  try {
+    graph = readJson<InteractionGraph>(paths.interactionGraphPath);
+  } catch {
+    // Graph is optional; L2/L3 will degrade gracefully without node metadata
+  }
+
   let selectorMap;
   try {
     selectorMap = readSelectorMap(repoRoot);
@@ -83,9 +95,10 @@ export function generatePlaywrightSpecs(repoRoot: string, opts?: { onlyRoutes?:
       if (s.kind === "api-smoke") {
         // API route: fetch-based test
         const methods = s.methods ?? ["GET"];
+        const apiNode = graph?.nodes.find(n => n.kind === "route" && n.path === s.route);
         const testCases = methods.map((method) => {
           return [
-            `  test(${JSON.stringify(`${method} ${s.route}`)}, async ({ baseURL }) => {`,
+            `  test(${JSON.stringify(`${method} ${s.route}`)}, async ({ request, baseURL }) => {`,
             `    const url = (baseURL ?? "http://localhost:3333") + ${JSON.stringify(s.route)};`,
             `    const res = await fetch(url, { method: ${JSON.stringify(method)} });`,
             `    expect(res.status).toBeLessThan(500);`,
@@ -95,16 +108,110 @@ export function generatePlaywrightSpecs(repoRoot: string, opts?: { onlyRoutes?:
           ].filter(Boolean).join("\n");
         });
 
+        // L2/L3 assertions for API routes
+        const apiOracleTests: string[] = [];
+        if ((s.oracleLevel === "L2" || s.oracleLevel === "L3") && apiNode) {
+          const l2 = generateL2Assertions(apiNode);
+          if (l2.length > 0) {
+            apiOracleTests.push([
+              `  test(${JSON.stringify(`L2 contract: ${s.route}`)}, async ({ request }) => {`,
+              ...l2.map(line => `    ${line}`),
+              `  });`,
+            ].join("\n"));
+          }
+        }
+        if (s.oracleLevel === "L3" && apiNode) {
+          const l3 = generateL3Assertions(apiNode, graph?.edges ?? []);
+          if (l3.length > 0) {
+            apiOracleTests.push([
+              `  test(${JSON.stringify(`L3 behavior: ${s.route}`)}, async ({ request }) => {`,
+              ...l3.map(line => `    ${line}`),
+              `  });`,
+            ].join("\n"));
+          }
+        }
+
         code = [
           specHeader(),
           `test.describe(${JSON.stringify(s.id)}, () => {`,
           ...testCases,
+          ...apiOracleTests,
+          `});`,
+          "",
+        ].join("\n");
+      } else if (s.kind === "ssr-verify") {
+        // SSR output verification
+        const routeUrl = s.route === "/" ? "/" : s.route;
+        const lines: string[] = [
+          specHeader(),
+          `test.describe(${JSON.stringify(s.id)}, () => {`,
+          `  test(${JSON.stringify(`ssr-verify ${s.route}`)}, async ({ page, baseURL }) => {`,
+          `    const url = (baseURL ?? "http://localhost:3333") + ${JSON.stringify(routeUrl)};`,
+          `    await page.goto(url);`,
+          `    const html = await page.content();`,
+          `    expect(html).toContain("<!DOCTYPE html>");`,
+          `    expect(html).toContain("<html");`,
+        ];
+        if (!s.hasIsland) {
+          lines.push(`    expect(html).not.toContain("data-mandu-island");`);
+        }
+        lines.push(`  });`, `});`, "");
+        code = lines.join("\n");
+      } else if (s.kind === "island-hydration") {
+        // Island hydration verification
+        const routeUrl = s.route === "/" ? "/" : s.route;
+        code = [
+          specHeader(),
+          `test.describe(${JSON.stringify(s.id)}, () => {`,
+          `  test(${JSON.stringify(`island-hydration ${s.route}`)}, async ({ page, baseURL }) => {`,
+          `    const url = (baseURL ?? "http://localhost:3333") + ${JSON.stringify(routeUrl)};`,
+          `    await page.goto(url);`,
+          `    await page.waitForSelector("[data-mandu-island]", { timeout: 5000 });`,
+          `    const count = await page.locator("[data-mandu-island]").count();`,
+          `    expect(count).toBeGreaterThan(0);`,
+          `  });`,
+          `});`,
+          "",
+        ].join("\n");
+      } else if (s.kind === "sse-stream") {
+        // SSE streaming test
+        code = [
+          specHeader(),
+          `test.describe(${JSON.stringify(s.id)}, () => {`,
+          `  test(${JSON.stringify(`sse-stream ${s.route}`)}, async ({ baseURL }) => {`,
+          `    const url = (baseURL ?? "http://localhost:3333") + ${JSON.stringify(s.route)};`,
+          `    const res = await fetch(url, { headers: { Accept: "text/event-stream" } });`,
+          `    expect(res.status).toBeLessThan(500);`,
+          `    const ct = res.headers.get("content-type") ?? "";`,
+          `    expect(ct).toContain("text/event-stream");`,
+          `    const body = await res.text();`,
+          `    expect(body.length).toBeGreaterThan(0);`,
+          `  });`,
+          `});`,
+          "",
+        ].join("\n");
+      } else if (s.kind === "form-action") {
+        // Form action test (POST with _action)
+        code = [
+          specHeader(),
+          `test.describe(${JSON.stringify(s.id)}, () => {`,
+          `  test(${JSON.stringify(`form-action ${s.route}`)}, async ({ baseURL }) => {`,
+          `    const url = (baseURL ?? "http://localhost:3333") + ${JSON.stringify(s.route)};`,
+          `    const res = await fetch(url, {`,
+          `      method: "POST",`,
+          `      headers: { "Content-Type": "application/x-www-form-urlencoded" },`,
+          `      body: "_action=default",`,
+          `    });`,
+          `    expect(res.status).toBeLessThan(500);`,
+          `    expect(res.headers.get("content-type")).toBeTruthy();`,
+          `  });`,
           `});`,
           "",
         ].join("\n");
       } else {
-        // Page route: browser-based test
-        const oracle = oracleTemplate(s.oracleLevel, s.route);
+        // Page route: browser-based test (route-smoke)
+        const graphNode = graph?.nodes.find(n => n.kind === "route" && n.path === s.route);
+        const oracle = oracleTemplate(s.oracleLevel, s.route, graphNode, graph?.edges);
 
         // Generate selector examples if selector map exists
         let selectorExamples = "";
@@ -117,7 +224,7 @@ export function generatePlaywrightSpecs(repoRoot: string, opts?: { onlyRoutes?:
         code = [
           specHeader(),
           `test.describe(${JSON.stringify(s.id)}, () => {`,
-          `  test(${JSON.stringify(`smoke ${s.route}`)}, async ({ page, baseURL }) => {`,
+          `  test(${JSON.stringify(`smoke ${s.route}`)}, async ({ page, request, baseURL }) => {`,
           `    const url = (baseURL ?? "http://localhost:3333") + ${JSON.stringify(s.route === "/" ? "/" : s.route)};`,
           `    ${oracle.setup.split("\n").join("\n    ")}`,
           `    await page.goto(url);`,

package/src/extractor.ts

@@ -1,5 +1,5 @@
 import fg from "fast-glob";
-import { relative, join } from "node:path";
+import { relative, join, dirname } from "node:path";
 import { createEmptyGraph, addEdge, addNode } from "./ir";
 import { getAtePaths, writeJson } from "./fs";
 import type { ExtractInput, InteractionGraph } from "./types";
@@ -89,6 +89,8 @@ export async function extract(input: ExtractInput): Promise<{ ok: true; graphPat
 
       // API route: extract HTTP methods from exports (GET, POST, PUT, PATCH, DELETE)
       let methods: string[] = [];
+      let hasSse = false;
+      let hasAction = false;
       if (isApiRoute) {
         const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
         const exportDecls = sourceFile.getExportedDeclarations();
@@ -98,14 +100,30 @@ export async function extract(input: ExtractInput): Promise<{ ok: true; graphPat
           }
         }
         if (methods.length === 0) methods = ["GET"]; // default
+
+        // Detect SSE and _action patterns from source text
+        const sourceText = sourceFile.getFullText();
+        hasSse = /ctx\.sse|text\/event-stream|EventSource|new\s+ReadableStream/.test(sourceText);
+        hasAction = methods.includes("POST") && /_action/.test(sourceText);
       }
 
+      // Detect companion island and contract files
+      const routeDir = dirname(filePath);
+      const hasIsland = [".island.tsx", ".island.ts", ".client.tsx", ".client.ts"]
+        .some(ext => fg.sync(`*${ext}`, { cwd: routeDir, onlyFiles: true }).length > 0);
+      const hasContract = [".contract.ts", ".contract.tsx"]
+        .some(ext => fg.sync(`*${ext}`, { cwd: routeDir, onlyFiles: true }).length > 0);
+
       addNode(graph, {
         kind: "route",
         id: routePath === "" ? "/" : routePath,
         file: relNormalized,
         path: routePath === "" ? "/" : routePath,
         ...(isApiRoute ? { methods } : {}),
+        ...(hasIsland ? { hasIsland: true } : {}),
+        ...(hasContract ? { hasContract: true } : {}),
+        ...(hasSse ? { hasSse: true } : {}),
+        ...(hasAction ? { hasAction: true } : {}),
       });
 
       // API route에는 JSX/navigation이 없으므로 건너뜀

package/src/index.ts

@@ -4,6 +4,7 @@ export { ATEFileError, ensureDir, readJson, writeJson, fileExists, getAtePaths }
 
 export { extract } from "./extractor";
 export { generateAndWriteScenarios } from "./scenario";
+export type { ScenarioKind, GeneratedScenario, ScenarioBundle } from "./scenario";
 export { generatePlaywrightSpecs } from "./codegen";
 export { runPlaywright } from "./runner";
 export { composeSummary, writeSummary, generateReport } from "./report";
@@ -20,6 +21,8 @@ export type {
   FailureCategory,
 } from "./heal";
 export { computeImpact } from "./impact";
+export { generateUnitSpec, generateUnitSpecs } from "./unit-codegen";
+export type { UnitCodegenResult } from "./unit-codegen";
 export * from "./selector-map";
 export { parseTrace, generateAlternativeSelectors } from "./trace-parser";
 export type { TraceAction, FailedLocator, TraceParseResult } from "./trace-parser";
@@ -27,7 +30,7 @@ export type { TraceAction, FailedLocator, TraceParseResult } from "./trace-parse
 // Oracle and domain detection
 export { detectDomain, detectDomainFromRoute, detectDomainFromSource } from "./domain-detector";
 export type { AppDomain, DomainDetectionResult } from "./domain-detector";
-export { generateL1Assertions, upgradeL0ToL1, getAssertionCount, createDefaultOracle } from "./oracle";
+export { generateL1Assertions, generateL2Assertions, generateL3Assertions, upgradeL0ToL1, getAssertionCount, createDefaultOracle } from "./oracle";
 export type { OracleResult } from "./oracle";
 
 import type { ExtractInput, GenerateInput, RunInput, ImpactInput, HealInput, OracleLevel } from "./types";

package/src/oracle.ts

@@ -1,4 +1,4 @@
-import type { OracleLevel } from "./types";
+import type { InteractionNode, OracleLevel } from "./types";
 import { detectDomain, type AppDomain } from "./domain-detector";
 
 export interface OracleResult {
@@ -150,3 +150,87 @@ export function getAssertionCount(domain: AppDomain, routePath: string): number
   const assertions = generateL1Assertions(domain, routePath);
   return assertions.filter((a) => a.includes("expect(")).length;
 }
+
+/**
+ * Generate L2 assertions: contract schema validation and SSR data verification
+ */
+export function generateL2Assertions(node: InteractionNode): string[] {
+  if (node.kind !== "route") return [];
+  const assertions: string[] = [];
+  const isApi = node.path.startsWith("/api/") || (node.methods && node.methods.length > 0);
+
+  if (isApi) {
+    assertions.push(`// L2: API contract validation`);
+    assertions.push(`const response = await request.get("${node.path}");`);
+    assertions.push(`expect(response.status()).toBeLessThan(500);`);
+    assertions.push(`const contentType = response.headers()["content-type"] ?? "";`);
+    assertions.push(`expect(contentType).toContain("application/json");`);
+    assertions.push(`const responseBody = await response.json();`);
+    assertions.push(`expect(responseBody).toBeDefined();`);
+    // Edge case: malformed body on POST endpoints
+    if (node.methods?.includes("POST") || node.methods?.includes("PUT")) {
+      assertions.push(`// Edge case: reject empty body on mutation endpoint`);
+      assertions.push(`const badResponse = await request.${node.methods.includes("POST") ? "post" : "put"}("${node.path}", { data: {} });`);
+      assertions.push(`expect(badResponse.status()).toBeGreaterThanOrEqual(400);`);
+      assertions.push(`expect(badResponse.status()).toBeLessThan(500);`);
+    }
+  } else {
+    // Page route: verify SSR data injection
+    assertions.push(`// L2: SSR data injection verification`);
+    assertions.push(`const manduDataEl = page.locator("#__MANDU_DATA__");`);
+    assertions.push(`const dataCount = await manduDataEl.count();`);
+    assertions.push(`if (dataCount > 0) {`);
+    assertions.push(`  const raw = await manduDataEl.textContent();`);
+    assertions.push(`  expect(() => JSON.parse(raw!)).not.toThrow();`);
+    assertions.push(`}`);
+  }
+
+  return assertions;
+}
+
+/**
+ * Generate L3 assertions: behavioral verification (state changes, island hydration, navigation)
+ */
+export function generateL3Assertions(node: InteractionNode, edges: { kind: string; to?: string }[]): string[] {
+  if (node.kind !== "route") return [];
+  const assertions: string[] = [];
+  const isApi = node.path.startsWith("/api/") || (node.methods && node.methods.length > 0);
+
+  if (isApi && node.methods?.includes("POST")) {
+    assertions.push(`// L3: POST state change verification`);
+    assertions.push(`const beforeRes = await request.get("${node.path}");`);
+    assertions.push(`const beforeStatus = beforeRes.status();`);
+    assertions.push(`if (beforeStatus < 400) {`);
+    assertions.push(`  const beforeBody = await beforeRes.json();`);
+    assertions.push(`  const beforeCount = Array.isArray(beforeBody) ? beforeBody.length : 0;`);
+    assertions.push(`  await request.post("${node.path}", { data: { _ate: true } });`);
+    assertions.push(`  const afterBody = await (await request.get("${node.path}")).json();`);
+    assertions.push(`  const afterCount = Array.isArray(afterBody) ? afterBody.length : 0;`);
+    assertions.push(`  expect(afterCount).toBeGreaterThanOrEqual(beforeCount);`);
+    assertions.push(`}`);
+  }
+
+  if (!isApi && node.hasIsland) {
+    assertions.push(`// L3: Island hydration verification`);
+    assertions.push(`const islands = page.locator("[data-mandu-island]");`);
+    assertions.push(`const islandCount = await islands.count();`);
+    assertions.push(`if (islandCount > 0) {`);
+    assertions.push(`  await expect(islands.first()).toBeVisible();`);
+    assertions.push(`  // Verify island has been hydrated (script loaded)`);
+    assertions.push(`  const hydrated = await page.evaluate(() => typeof window.__MANDU_ISLANDS__ === "object");`);
+    assertions.push(`  expect(hydrated).toBe(true);`);
+    assertions.push(`}`);
+  }
+
+  // Navigation flow: verify that outgoing links resolve to valid pages
+  const navTargets = edges.filter(e => e.kind === "navigate" && e.to).slice(0, 3);
+  if (!isApi && navTargets.length > 0) {
+    assertions.push(`// L3: Navigation flow verification`);
+    for (const nav of navTargets) {
+      assertions.push(`const navRes_${nav.to!.replace(/[^a-zA-Z0-9]/g, "_")} = await request.get("${nav.to}");`);
+      assertions.push(`expect(navRes_${nav.to!.replace(/[^a-zA-Z0-9]/g, "_")}.status()).toBeLessThan(500);`);
+    }
+  }
+
+  return assertions;
+}

package/src/pipeline.ts

@@ -126,6 +126,7 @@ export async function runFullPipeline(options: AutoPipelineOptions): Promise<Aut
         repoRoot: options.repoRoot,
         baseURL: options.baseURL,
         ci: options.ci,
+        onlyRoutes: impactResult?.selectedRoutes,
       });
       runId = runResult.runId;
       exitCode = runResult.exitCode;

package/src/runner.ts

@@ -56,6 +56,14 @@ export async function runPlaywright(input: RunInput): Promise<RunResult> {
     "tests/e2e/playwright.config.ts",
   ];
 
+  // Route filtering: pass --grep to Playwright so only matching specs run
+  if (input.onlyRoutes && input.onlyRoutes.length > 0) {
+    const grepPattern = input.onlyRoutes
+      .map((r) => r.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+      .join("|");
+    args.push("--grep", grepPattern);
+  }
+
   const env = {
     ...process.env,
     CI: input.ci ? "true" : process.env.CI,

package/src/scenario.ts

@@ -1,11 +1,14 @@
 import type { InteractionGraph, OracleLevel } from "./types";
 import { getAtePaths, readJson, writeJson } from "./fs";
 
+export type ScenarioKind = "route-smoke" | "api-smoke" | "ssr-verify" | "island-hydration" | "sse-stream" | "form-action";
+
 export interface GeneratedScenario {
   id: string;
-  kind: "route-smoke" | "api-smoke";
+  kind: ScenarioKind;
   route: string;
   methods?: string[];
+  hasIsland?: boolean;
   oracleLevel: OracleLevel;
 }
 
@@ -29,22 +32,70 @@ export function generateScenariosFromGraph(graph: InteractionGraph, oracleLevel:
     throw new Error("빈 interaction graph입니다 (nodes가 없습니다)");
   }
 
-  const routes = graph.nodes.filter((n) => n.kind === "route") as Array<{ kind: "route"; id: string; path: string; methods?: string[] }>;
+  const routes = graph.nodes.filter((n) => n.kind === "route") as Array<{ kind: "route"; id: string; path: string; methods?: string[]; hasIsland?: boolean; hasSse?: boolean; hasAction?: boolean }>;
 
   if (routes.length === 0) {
     console.warn("[ATE] 경고: route가 없습니다. 빈 시나리오 번들을 생성합니다.");
   }
 
-  const scenarios: GeneratedScenario[] = routes.map((r) => {
+  const scenarios: GeneratedScenario[] = [];
+
+  for (const r of routes) {
     const isApi = r.path.startsWith("/api/") || (r.methods && r.methods.length > 0);
-    return {
+
+    // Baseline smoke test for every route
+    scenarios.push({
       id: `${isApi ? "api" : "route"}:${r.id}`,
       kind: isApi ? "api-smoke" : "route-smoke",
       route: r.id,
       ...(isApi && r.methods ? { methods: r.methods } : {}),
       oracleLevel,
-    };
-  });
+    });
+
+    if (!isApi) {
+      // SSR verification for all page routes
+      scenarios.push({
+        id: `${r.id}--ssr-verify`,
+        kind: "ssr-verify",
+        route: r.id,
+        hasIsland: !!r.hasIsland,
+        oracleLevel,
+      });
+
+      // Island hydration for pages with islands
+      if (r.hasIsland) {
+        scenarios.push({
+          id: `${r.id}--island-hydration`,
+          kind: "island-hydration",
+          route: r.id,
+          oracleLevel,
+        });
+      }
+    }
+
+    if (isApi) {
+      // SSE stream test for API routes with SSE
+      if (r.hasSse) {
+        scenarios.push({
+          id: `${r.id}--sse-stream`,
+          kind: "sse-stream",
+          route: r.id,
+          oracleLevel,
+        });
+      }
+
+      // Form action test for API routes with POST + _action
+      if (r.hasAction) {
+        scenarios.push({
+          id: `${r.id}--form-action`,
+          kind: "form-action",
+          route: r.id,
+          methods: r.methods,
+          oracleLevel,
+        });
+      }
+    }
+  }
 
   return {
     schemaVersion: 1,

package/src/types.ts

@@ -36,7 +36,7 @@ export interface InteractionGraph {
 }
 
 export type InteractionNode =
-  | { kind: "route"; id: string; file: string; path: string; methods?: string[] }
+  | { kind: "route"; id: string; file: string; path: string; methods?: string[]; hasIsland?: boolean; hasContract?: boolean; hasSse?: boolean; hasAction?: boolean }
   | { kind: "modal"; id: string; file: string; name: string }
   | { kind: "action"; id: string; file: string; name: string };
 
@@ -57,6 +57,8 @@ export interface RunInput {
   ci?: boolean;
   headless?: boolean;
   browsers?: ("chromium" | "firefox" | "webkit")[];
+  /** Filter test execution to specs matching these route paths (e.g. ["/api/users", "/dashboard"]) */
+  onlyRoutes?: string[];
 }
 
 export interface ImpactInput {

package/src/unit-codegen.ts

@@ -0,0 +1,83 @@
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { ensureDir, getAtePaths, readJson } from "./fs";
+import type { InteractionGraph, InteractionNode } from "./types";
+
+type RouteNode = Extract<InteractionNode, { kind: "route" }>;
+
+/**
+ * Generate a bun:test unit spec for a single route node using testFilling.
+ */
+export function generateUnitSpec(route: RouteNode): string {
+  const lines: string[] = [];
+  lines.push(`import { testFilling } from "@mandujs/core/testing";`);
+  lines.push(`import { describe, it, expect } from "bun:test";`);
+  lines.push(`import route from "${route.file}";`);
+  lines.push(``);
+  lines.push(`describe("${route.id}", () => {`);
+
+  const methods = route.methods ?? ["GET"];
+
+  if (methods.includes("GET")) {
+    lines.push(`  it("GET returns 200", async () => {`);
+    lines.push(`    const res = await testFilling(route, { method: "GET" });`);
+    lines.push(`    expect(res.status).toBe(200);`);
+    lines.push(`  });`);
+  }
+
+  if (methods.includes("POST")) {
+    lines.push(`  it("POST with valid body returns 200/201", async () => {`);
+    lines.push(`    const res = await testFilling(route, { method: "POST", body: {} });`);
+    lines.push(`    expect([200, 201]).toContain(res.status);`);
+    lines.push(`  });`);
+  }
+
+  lines.push(`});`);
+  return lines.join("\n");
+}
+
+export interface UnitCodegenResult {
+  files: string[];
+  warnings: string[];
+}
+
+/**
+ * Generate bun:test unit specs for all route nodes in the interaction graph.
+ * Writes files to tests/unit/auto/ under the repo root.
+ */
+export function generateUnitSpecs(repoRoot: string, opts?: { onlyRoutes?: string[] }): UnitCodegenResult {
+  const paths = getAtePaths(repoRoot);
+  const warnings: string[] = [];
+
+  let graph: InteractionGraph;
+  try {
+    graph = readJson<InteractionGraph>(paths.interactionGraphPath);
+  } catch (err: unknown) {
+    throw new Error(`Interaction graph read failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const routes = graph.nodes.filter((n): n is RouteNode => n.kind === "route");
+  if (routes.length === 0) {
+    warnings.push("No route nodes found in interaction graph");
+    return { files: [], warnings };
+  }
+
+  const outDir = join(repoRoot, "tests", "unit", "auto");
+  ensureDir(outDir);
+
+  const files: string[] = [];
+  for (const route of routes) {
+    if (opts?.onlyRoutes?.length && !opts.onlyRoutes.includes(route.id)) continue;
+
+    const safeId = route.id.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const filePath = join(outDir, `${safeId}.test.ts`);
+    try {
+      writeFileSync(filePath, generateUnitSpec(route), "utf8");
+      files.push(filePath);
+    } catch (err: unknown) {
+      warnings.push(`Failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { files, warnings };
+}