@elench/testkit 0.1.60 → 0.1.62

package/lib/coverage/index.test.mjs

@@ -13,7 +13,7 @@ afterEach(() => {
 });
 
 describe("coverage graph builder", () => {
-  it("builds a Next page -> request -> API route -> server capability graph", () => {
+  it("builds a Next page -> surface -> action -> request -> API route -> backend/data capability graph", () => {
     const productDir = createProduct();
     writeFile(
       productDir,
@@ -38,15 +38,35 @@ describe("coverage graph builder", () => {
       "src/app/campaigns/page.tsx",
       `
         "use client";
-        import { getJson } from "@/client/http/http";
+        import { getJson, postJson } from "@/client/http/http";
 
-        export default async function CampaignsPage() {
+        async function refreshCampaigns() {
           await getJson("/api/campaigns");
-          return null;
+        }
+
+        async function createCampaign() {
+          await postJson("/api/campaigns");
+        }
+
+        export default function CampaignsPage() {
+          return (
+            <main>
+              <button data-testid="campaign-refresh-button" onClick={() => refreshCampaigns()}>
+                Refresh campaigns
+              </button>
+              <button data-testid="campaign-create-button" onClick={createCampaign}>
+                Create campaign
+              </button>
+            </main>
+          );
         }
       `
     );
-    writeFile(productDir, "src/client/http/http.ts", `export function getJson() { return null; }`);
+    writeFile(
+      productDir,
+      "src/client/http/http.ts",
+      `export function getJson() { return null; }\nexport function postJson() { return null; }`
+    );
     writeFile(
       productDir,
       "src/app/api/campaigns/route.ts",
@@ -62,7 +82,26 @@ describe("coverage graph builder", () => {
         }
       `
     );
-    writeFile(productDir, "src/backend/server/campaigns/index.ts", `export async function listCampaigns() {}\nexport async function createCampaign() {}`);
+    writeFile(
+      productDir,
+      "src/backend/server/campaigns/index.ts",
+      `
+        import { insertCampaignRow, selectCampaignRows } from "@/backend/data/campaigns";
+
+        export async function listCampaigns() {
+          return selectCampaignRows();
+        }
+
+        export async function createCampaign() {
+          return insertCampaignRow();
+        }
+      `
+    );
+    writeFile(
+      productDir,
+      "src/backend/data/campaigns/index.ts",
+      `export async function selectCampaignRows() {}\nexport async function insertCampaignRow() {}`
+    );
 
     const context = buildServiceCoverageContext(productDir, "web", {
       local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
@@ -73,6 +112,10 @@ describe("coverage graph builder", () => {
       route: "/campaigns",
       filePath: "src/app/campaigns/page.tsx",
     });
+    expect(context.pageByRoute.get("/campaigns").surfacesByTargetValue.get("campaign-refresh-button")).toMatchObject({
+      kind: "ui_surface",
+      label: "Refresh campaigns",
+    });
     expect(context.apiRouteByKey.get("GET:/api/campaigns").node).toMatchObject({
       kind: "api_route",
       route: "/campaigns",
@@ -83,8 +126,18 @@ describe("coverage graph builder", () => {
     expect(context.graph.edges).toEqual(
       expect.arrayContaining([
         expect.objectContaining({
-          kind: "requests",
+          kind: "contains",
           from: "page_view:web:/campaigns",
+          to: "ui_surface:web:/campaigns:campaign-refresh-button",
+        }),
+        expect.objectContaining({
+          kind: "triggers",
+          from: "ui_surface:web:/campaigns:campaign-refresh-button",
+          to: expect.stringContaining("ui_action:web:/campaigns"),
+        }),
+        expect.objectContaining({
+          kind: "requests",
+          from: expect.stringContaining("ui_action:web:/campaigns"),
         }),
         expect.objectContaining({
           kind: "handles",
@@ -94,6 +147,11 @@ describe("coverage graph builder", () => {
           kind: "delegates_to",
           from: "api_route:web:GET:/api/campaigns",
         }),
+        expect.objectContaining({
+          kind: "delegates_to",
+          from: "server_capability:src/backend/server/campaigns#createCampaign",
+          to: "data_capability:src/backend/data/campaigns#insertCampaignRow",
+        }),
       ])
     );
   });
@@ -107,8 +165,13 @@ describe("coverage graph builder", () => {
         import { saveSettings } from "./actions";
 
         export default function SettingsPage() {
-          void saveSettings;
-          return null;
+          return (
+            <form action={saveSettings}>
+              <button data-testid="settings-save-button" type="submit">
+                Save settings
+              </button>
+            </form>
+          );
         }
       `
     );
@@ -138,7 +201,12 @@ describe("coverage graph builder", () => {
       expect.arrayContaining([
         expect.objectContaining({
           kind: "triggers",
-          from: "page_view:web:/settings",
+          from: expect.stringContaining("ui_surface:web:/settings"),
+          to: "ui_action:web:/settings:saveSettings",
+        }),
+        expect.objectContaining({
+          kind: "triggers",
+          from: "ui_action:web:/settings:saveSettings",
           to: "server_action:web:src/app/settings/actions.ts#saveSettings",
         }),
         expect.objectContaining({
@@ -149,10 +217,48 @@ describe("coverage graph builder", () => {
     );
   });
 
-  it("attaches convention-based test evidence to page and route nodes", () => {
+  it("attaches convention-based test evidence to page, surface, route, and data nodes", () => {
     const productDir = createProduct();
-    writeFile(productDir, "src/app/campaigns/page.tsx", `export default function CampaignsPage() { return null; }`);
-    writeFile(productDir, "src/app/api/campaigns/route.ts", `export async function GET() { return Response.json({ ok: true }); }`);
+    writeFile(
+      productDir,
+      "src/app/campaigns/page.tsx",
+      `
+        "use client";
+        import { getJson } from "@/client/http/http";
+
+        async function loadCampaigns() {
+          await getJson("/api/campaigns");
+        }
+
+        export default function CampaignsPage() {
+          return <button data-testid="campaign-save-button" onClick={loadCampaigns}>Save campaign</button>;
+        }
+      `
+    );
+    writeFile(productDir, "src/client/http/http.ts", `export async function getJson() { return null; }`);
+    writeFile(
+      productDir,
+      "src/app/api/campaigns/route.ts",
+      `
+        import { listCampaigns } from "@/backend/server/campaigns";
+
+        export async function GET() {
+          return listCampaigns();
+        }
+      `
+    );
+    writeFile(
+      productDir,
+      "src/backend/server/campaigns/index.ts",
+      `
+        import { saveCampaignRow } from "@/backend/data/campaigns";
+
+        export async function listCampaigns() {
+          return saveCampaignRow();
+        }
+      `
+    );
+    writeFile(productDir, "src/backend/data/campaigns/index.ts", `export async function saveCampaignRow() {}`);
     writeFile(
       productDir,
       "src/app/campaigns/__testkit__/campaigns.pw.testkit.ts",
@@ -165,6 +271,32 @@ describe("coverage graph builder", () => {
         });
       `
     );
+    writeFile(
+      productDir,
+      "src/app/api/campaigns/__testkit__/campaigns.int.testkit.ts",
+      `
+        import { defineHttpSuite } from "@elench/testkit";
+
+        const suite = defineHttpSuite(({ rawReq }) => {
+          rawReq("GET", "/api/campaigns");
+        });
+
+        export default suite;
+      `
+    );
+    writeFile(
+      productDir,
+      "src/backend/data/campaigns/__testkit__/campaigns.dal.testkit.ts",
+      `
+        import { defineDalSuite } from "@elench/testkit";
+
+        const suite = defineDalSuite(({ db }) => {
+          db.query("SELECT 1 AS value");
+        });
+
+        export default suite;
+      `
+    );
 
     const graph = buildCoverageGraph({
       productDir,
@@ -188,6 +320,13 @@ describe("coverage graph builder", () => {
           suiteName: "campaigns",
           filePath: "src/app/api/campaigns/__testkit__/campaigns.int.testkit.ts",
         },
+        {
+          serviceName: "web",
+          type: "dal",
+          framework: "k6",
+          suiteName: "campaigns",
+          filePath: "src/backend/data/campaigns/__testkit__/campaigns.dal.testkit.ts",
+        },
       ],
     });
 
@@ -195,7 +334,10 @@ describe("coverage graph builder", () => {
       expect.arrayContaining([
         expect.objectContaining({
           testFilePath: "src/app/campaigns/__testkit__/campaigns.pw.testkit.ts",
-          coveredNodeIds: ["page_view:web:/campaigns"],
+          coveredNodeIds: expect.arrayContaining([
+            "page_view:web:/campaigns",
+            "ui_surface:web:/campaigns:campaign-save-button",
+          ]),
           details: expect.objectContaining({
             route: "/campaigns",
             targets: [
@@ -210,6 +352,12 @@ describe("coverage graph builder", () => {
           testFilePath: "src/app/api/campaigns/__testkit__/campaigns.int.testkit.ts",
           coveredNodeIds: ["api_route:web:GET:/api/campaigns"],
         }),
+        expect.objectContaining({
+          testFilePath: "src/backend/data/campaigns/__testkit__/campaigns.dal.testkit.ts",
+          coveredNodeIds: expect.arrayContaining([
+            expect.stringContaining("data_capability:src/backend/data/campaigns"),
+          ]),
+        }),
       ])
     );
   });
@@ -227,6 +375,174 @@ describe("coverage graph builder", () => {
     expect(context.apiRouteByKey.get("GET:/api/projects/[projectId]").node).toBeTruthy();
   });
 
+  it("resolves root-level PW test via page.goto() content extraction", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/dashboard/page.tsx",
+      `export default function DashboardPage() { return <button data-testid="dash-header">Dashboard</button>; }`
+    );
+    writeFile(
+      productDir,
+      "__testkit__/dashboard.pw.testkit.ts",
+      `
+        import { test, expect } from "@playwright/test";
+        test("dashboard loads", async ({ page }) => {
+          await page.goto("/dashboard");
+          await expect(page.getByTestId("dash-header")).toBeVisible();
+        });
+      `
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "e2e",
+          framework: "playwright",
+          suiteName: "dashboard",
+          filePath: "__testkit__/dashboard.pw.testkit.ts",
+        },
+      ],
+    });
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/dashboard.pw.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual(
+      expect.arrayContaining([
+        "page_view:web:/dashboard",
+        "ui_surface:web:/dashboard:dash-header",
+      ])
+    );
+  });
+
+  it("resolves root-level e2e test via rawReq content extraction", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/api/projects/route.ts",
+      `export async function GET() { return Response.json({ ok: true }); }`
+    );
+    writeFile(
+      productDir,
+      "__testkit__/projects.e2e.testkit.ts",
+      `
+        import { defineHttpSuite } from "@elench/testkit";
+        export default defineHttpSuite(({ rawReq }) => {
+          rawReq("GET", "/api/projects");
+        });
+      `
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "e2e",
+          framework: "k6",
+          suiteName: "projects",
+          filePath: "__testkit__/projects.e2e.testkit.ts",
+        },
+      ],
+    });
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/projects.e2e.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual(["api_route:web:GET:/api/projects"]);
+  });
+
+  it("resolves scenario test via rawReq content extraction", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/api/campaigns/route.ts",
+      `export async function POST() { return Response.json({ ok: true }); }`
+    );
+    writeFile(
+      productDir,
+      "__testkit__/campaign-flow.scenario.testkit.ts",
+      `
+        import { defineHttpSuite } from "@elench/testkit";
+        export default defineHttpSuite(({ rawReq }) => {
+          rawReq("POST", "/api/campaigns");
+        });
+      `
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "scenario",
+          framework: "k6",
+          suiteName: "campaign-flow",
+          filePath: "__testkit__/campaign-flow.scenario.testkit.ts",
+        },
+      ],
+    });
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/campaign-flow.scenario.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual(["api_route:web:POST:/api/campaigns"]);
+  });
+
+  it("emits zero-coverage-inferred diagnostic when no patterns match", () => {
+    const productDir = createProduct();
+    writeFile(productDir, "src/app/page.tsx", `export default function HomePage() { return null; }`);
+    writeFile(
+      productDir,
+      "__testkit__/misc.e2e.testkit.ts",
+      `// no recognizable patterns here\nconsole.log("hello");`
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "e2e",
+          framework: "k6",
+          suiteName: "misc",
+          filePath: "__testkit__/misc.e2e.testkit.ts",
+        },
+      ],
+    });
+
+    expect(graph.diagnostics).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          level: "info",
+          code: "zero-coverage-inferred",
+          filePath: "__testkit__/misc.e2e.testkit.ts",
+          service: "web",
+        }),
+      ])
+    );
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/misc.e2e.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual([expect.stringContaining("test_file:web:")]);
+  });
+
   it("does not exclude app/coverage source routes while still allowing top-level coverage output to be ignored", () => {
     const productDir = createProduct();
     writeFile(productDir, "app/coverage/page.tsx", `export default function CoveragePage() { return null; }`);

package/lib/coverage/next-discovery.mjs

@@ -0,0 +1,174 @@
+import fs from "fs";
+import path from "path";
+import { analyzeNextPageFile } from "./next-static-analysis.mjs";
+import { extractBackendImports, extractExportedFunctions, extractExportedMethodBodies } from "./backend-discovery.mjs";
+import { resolveImportToSourceFile, walkFiles } from "./fs-walk.mjs";
+import { routeFromApiFile, routeFromAppFile } from "./routing.mjs";
+import {
+  dedupeNodes,
+  hasWord,
+  HTTP_METHODS,
+  isServerActionFile,
+  normalizePath,
+  normalizeRoute,
+  pageLabelFromRoute,
+  toApiRequestPath,
+} from "./shared.mjs";
+
+export function discoverPageViews({ serviceName, serviceRoot, nextAppRoot, exclude = [], resolveImportToSourceFile }) {
+  const pageFiles = walkFiles(nextAppRoot, { baseDir: serviceRoot, exclude }).filter(
+    (filePath) => filePath.endsWith("/page.tsx") || filePath.endsWith("/page.ts")
+  );
+  const nodes = [];
+  const edges = [];
+  const pageEntries = [];
+
+  for (const absolutePath of pageFiles) {
+    const relativePath = normalizePath(path.relative(serviceRoot, absolutePath));
+    const route = routeFromAppFile(nextAppRoot, absolutePath);
+    const content = fs.readFileSync(absolutePath, "utf8");
+    const node = {
+      id: `page_view:${serviceName}:${route}`,
+      kind: "page_view",
+      service: serviceName,
+      label: pageLabelFromRoute(route),
+      route,
+      filePath: relativePath,
+    };
+    nodes.push(node);
+
+    const pageAnalysis = analyzeNextPageFile({
+      serviceName,
+      serviceRoot,
+      filePath: relativePath,
+      route,
+      content,
+      readSourceFile: (resolvedPath) => {
+        const absoluteResolved = path.join(serviceRoot, resolvedPath);
+        return fs.existsSync(absoluteResolved) ? fs.readFileSync(absoluteResolved, "utf8") : null;
+      },
+      resolveImportPath: (specifier) => resolveImportToSourceFile(serviceRoot, relativePath, specifier),
+      isServerActionFile,
+      normalizeRoute,
+    });
+
+    for (const analysisNode of pageAnalysis.nodes) nodes.push(analysisNode);
+    for (const analysisEdge of pageAnalysis.edges) edges.push(analysisEdge);
+
+    pageEntries.push({
+      node,
+      route,
+      filePath: relativePath,
+      requests: pageAnalysis.requests,
+      serverActionRefs: pageAnalysis.serverActionRefs,
+      surfacesByTargetValue: pageAnalysis.surfacesByTargetValue,
+    });
+  }
+
+  return { nodes, edges, pageEntries };
+}
+
+export function discoverApiRoutes({ serviceName, serviceRoot, nextAppRoot, exclude = [], resolveImportToSourceFile }) {
+  const routeFiles = walkFiles(path.join(nextAppRoot, "api"), { baseDir: serviceRoot, exclude }).filter(
+    (filePath) => filePath.endsWith("/route.ts") || filePath.endsWith("/route.tsx") || filePath.endsWith("/route.js")
+  );
+  const nodes = [];
+  const edges = [];
+  const routeEntries = [];
+
+  for (const absolutePath of routeFiles) {
+    const filePath = normalizePath(path.relative(serviceRoot, absolutePath));
+    const route = routeFromApiFile(nextAppRoot, absolutePath);
+    const requestPath = toApiRequestPath(route);
+    const content = fs.readFileSync(absolutePath, "utf8");
+    const methodBodies = extractExportedMethodBodies(content, HTTP_METHODS);
+    const backendImports = extractBackendImports({ serviceName, serviceRoot, filePath, content, resolveImportToSourceFile });
+
+    for (const [method, body] of methodBodies) {
+      const node = {
+        id: `api_route:${serviceName}:${method}:${requestPath}`,
+        kind: "api_route",
+        service: serviceName,
+        label: `${method} ${requestPath}`,
+        route,
+        method,
+        path: requestPath,
+        filePath,
+      };
+      nodes.push(node);
+
+      const matchedCapabilities = backendImports.filter((entry) => hasWord(body, entry.importName));
+      for (const capability of matchedCapabilities) {
+        nodes.push(capability.node);
+        edges.push({
+          id: `delegates_to:${node.id}:${capability.node.id}`,
+          kind: "delegates_to",
+          from: node.id,
+          to: capability.node.id,
+          confidence: "high",
+        });
+      }
+
+      routeEntries.push({ node, method, route, requestPath, filePath });
+    }
+  }
+
+  return { nodes: dedupeNodes(nodes), edges, routeEntries };
+}
+
+export function discoverServerActions({ serviceName, serviceRoot, exclude = [], resolveImportToSourceFile }) {
+  const appRoots = [path.join(serviceRoot, "app"), path.join(serviceRoot, "src", "app")].filter((candidate) =>
+    fs.existsSync(candidate)
+  );
+  const nodes = [];
+  const edges = [];
+  const actionEntries = [];
+
+  for (const appRoot of appRoots) {
+    for (const absolutePath of walkFiles(appRoot, { baseDir: serviceRoot, exclude })) {
+      if (!absolutePath.endsWith(".ts") && !absolutePath.endsWith(".tsx")) continue;
+      const content = fs.readFileSync(absolutePath, "utf8");
+      if (!isServerActionFile(content)) continue;
+
+      const relativePath = normalizePath(path.relative(serviceRoot, absolutePath));
+      const backendImports = extractBackendImports({
+        serviceName,
+        serviceRoot,
+        filePath: relativePath,
+        content,
+        resolveImportToSourceFile,
+      });
+      const exportedFunctions = extractExportedFunctions(content);
+
+      for (const exported of exportedFunctions) {
+        const node = {
+          id: `server_action:${serviceName}:${relativePath}#${exported.name}`,
+          kind: "server_action",
+          service: serviceName,
+          label: exported.name,
+          filePath: relativePath,
+        };
+        nodes.push(node);
+        actionEntries.push({
+          node,
+          exportName: exported.name,
+          sourceFile: relativePath,
+        });
+
+        const matchedCapabilities = backendImports.filter((entry) => hasWord(exported.body, entry.importName));
+        for (const capability of matchedCapabilities) {
+          nodes.push(capability.node);
+          edges.push({
+            id: `delegates_to:${node.id}:${capability.node.id}`,
+            kind: "delegates_to",
+            from: node.id,
+            to: capability.node.id,
+            confidence: "high",
+          });
+        }
+      }
+    }
+  }
+
+  return { nodes: dedupeNodes(nodes), edges, actionEntries };
+}