@elench/testkit 0.1.57 → 0.1.59

package/lib/coverage/index.test.mjs

@@ -0,0 +1,241 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildCoverageGraph, buildServiceCoverageContext } from "./index.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("coverage graph builder", () => {
+  it("builds a Next page -> request -> API route -> server capability graph", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "testkit.setup.ts",
+      `
+        import { defineTestkitSetup, nextService } from "@elench/testkit/setup";
+
+        export default defineTestkitSetup({
+          services: {
+            web: nextService({
+              cwd: ".",
+              start: "node server.js",
+              baseUrl: "http://127.0.0.1:3000",
+              readyUrl: "http://127.0.0.1:3000"
+            })
+          }
+        });
+      `
+    );
+    writeFile(
+      productDir,
+      "src/app/campaigns/page.tsx",
+      `
+        "use client";
+        import { getJson } from "@/client/http/http";
+
+        export default async function CampaignsPage() {
+          await getJson("/api/campaigns");
+          return null;
+        }
+      `
+    );
+    writeFile(productDir, "src/client/http/http.ts", `export function getJson() { return null; }`);
+    writeFile(
+      productDir,
+      "src/app/api/campaigns/route.ts",
+      `
+        import { listCampaigns, createCampaign } from "@/backend/server/campaigns";
+
+        export async function GET() {
+          return listCampaigns();
+        }
+
+        export async function POST() {
+          return createCampaign();
+        }
+      `
+    );
+    writeFile(productDir, "src/backend/server/campaigns/index.ts", `export async function listCampaigns() {}\nexport async function createCampaign() {}`);
+
+    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" },
+    });
+
+    expect(context.pageByRoute.get("/campaigns").node).toMatchObject({
+      kind: "page_view",
+      route: "/campaigns",
+      filePath: "src/app/campaigns/page.tsx",
+    });
+    expect(context.apiRouteByKey.get("GET:/api/campaigns").node).toMatchObject({
+      kind: "api_route",
+      route: "/campaigns",
+      method: "GET",
+      path: "/api/campaigns",
+      filePath: "src/app/api/campaigns/route.ts",
+    });
+    expect(context.graph.edges).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: "requests",
+          from: "page_view:web:/campaigns",
+        }),
+        expect.objectContaining({
+          kind: "handles",
+          to: "api_route:web:GET:/api/campaigns",
+        }),
+        expect.objectContaining({
+          kind: "delegates_to",
+          from: "api_route:web:GET:/api/campaigns",
+        }),
+      ])
+    );
+  });
+
+  it("discovers server action links from pages", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/settings/page.tsx",
+      `
+        import { saveSettings } from "./actions";
+
+        export default function SettingsPage() {
+          void saveSettings;
+          return null;
+        }
+      `
+    );
+    writeFile(
+      productDir,
+      "src/app/settings/actions.ts",
+      `
+        "use server";
+        import { updateSettings } from "@/backend/server/settings";
+
+        export async function saveSettings() {
+          return updateSettings();
+        }
+      `
+    );
+    writeFile(productDir, "src/backend/server/settings.ts", `export async function updateSettings() {}`);
+
+    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" },
+    });
+
+    expect(context.serverActionByExportKey.get("src/app/settings/actions.ts#saveSettings").node).toMatchObject({
+      kind: "server_action",
+      label: "saveSettings",
+    });
+    expect(context.graph.edges).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: "triggers",
+          from: "page_view:web:/settings",
+          to: "server_action:web:src/app/settings/actions.ts#saveSettings",
+        }),
+        expect.objectContaining({
+          kind: "delegates_to",
+          from: "server_action:web:src/app/settings/actions.ts#saveSettings",
+        }),
+      ])
+    );
+  });
+
+  it("attaches convention-based test evidence to page and route 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 }); }`);
+
+    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: "campaigns",
+          filePath: "src/app/campaigns/__testkit__/campaigns.pw.testkit.ts",
+        },
+        {
+          serviceName: "web",
+          type: "integration",
+          framework: "k6",
+          suiteName: "campaigns",
+          filePath: "src/app/api/campaigns/__testkit__/campaigns.int.testkit.ts",
+        },
+      ],
+    });
+
+    expect(graph.evidence).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          testFilePath: "src/app/campaigns/__testkit__/campaigns.pw.testkit.ts",
+          coveredNodeIds: ["page_view:web:/campaigns"],
+        }),
+        expect.objectContaining({
+          testFilePath: "src/app/api/campaigns/__testkit__/campaigns.int.testkit.ts",
+          coveredNodeIds: ["api_route:web:GET:/api/campaigns"],
+        }),
+      ])
+    );
+  });
+
+  it("normalizes dynamic routes", () => {
+    const productDir = createProduct();
+    writeFile(productDir, "src/app/projects/[projectId]/page.tsx", `export default function ProjectPage() { return null; }`);
+    writeFile(productDir, "src/app/api/projects/[projectId]/route.ts", `export async function GET() { return Response.json({ ok: true }); }`);
+
+    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" },
+    });
+
+    expect(context.pageByRoute.get("/projects/[projectId]").node).toBeTruthy();
+    expect(context.apiRouteByKey.get("GET:/api/projects/[projectId]").node).toBeTruthy();
+  });
+
+  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; }`);
+    writeFile(productDir, "coverage/page.tsx", `export default function OutputPage() { return null; }`);
+
+    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" },
+        discovery: { roots: ["app"] },
+      },
+      { exclude: ["coverage"] }
+    );
+
+    expect(context.pageByRoute.get("/coverage").node).toMatchObject({
+      filePath: "app/coverage/page.tsx",
+    });
+    expect(context.graph.nodes.some((node) => node.filePath === "coverage/page.tsx")).toBe(false);
+  });
+});
+
+function createProduct() {
+  const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-coverage-"));
+  cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+  return productDir;
+}
+
+function writeFile(productDir, relativePath, content = "export {};\n") {
+  const absolutePath = path.join(productDir, relativePath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content);
+}

package/lib/discovery/index.d.ts

@@ -1,3 +1,5 @@
+import type { CoverageGraph } from "@elench/testkit-protocol";
+
 export type DiscoverySelectionType = "int" | "e2e" | "scenario" | "dal" | "load" | "pw";
 export type DiscoveryInternalType = "integration" | "e2e" | "scenario" | "dal" | "load";
 export type DiscoveryFramework = "k6" | "playwright";
@@ -86,6 +88,7 @@ export interface DiscoveryResult {
   services: DiscoveryService[];
   suites: DiscoverySuite[];
   files: DiscoveryFile[];
+  coverageGraph: CoverageGraph | null;
   diagnostics: DiscoveryDiagnostic[];
   summary: {
     services: number;

package/lib/discovery/index.mjs

@@ -2,6 +2,7 @@ import path from "path";
 import { loadConfigContext, resolveProductDir } from "../config/index.mjs";
 import { discoverProject } from "../config/discovery.mjs";
 import { loadTestkitSetup } from "../config/setup-loader.mjs";
+import { buildCoverageGraph } from "../coverage/index.mjs";
 import { historyFilePath, loadHistory, summarizeHistoryForFiles } from "../history/index.mjs";
 import {
   matchesSelectedTypes,
@@ -11,7 +12,7 @@ import {
   suiteSelectionType,
 } from "../runner/suite-selection.mjs";
 
-const DISCOVERY_SCHEMA_VERSION = 1;
+const DISCOVERY_SCHEMA_VERSION = 3;
 
 export async function discoverTests(options = {}) {
   const productDir = resolveProductDir(process.cwd(), options.dir);
@@ -36,6 +37,7 @@ export async function discoverTests(options = {}) {
     services: [],
     suites: [],
     files: [],
+    coverageGraph: null,
     diagnostics: [...setupContext.diagnostics],
     summary: emptySummary(),
     history: {
@@ -45,11 +47,12 @@ export async function discoverTests(options = {}) {
   };
 
   if (!setupContext.setup) {
-    return finalizeDiscoveryResult(baseResult);
+    return finalizeDiscoveryResult(baseResult, productDir);
   }
 
   const rawDiscovery = discoverProject(productDir, setupContext.setup.services || {}, {
     strict: filters.diagnosticsMode === "error",
+    discovery: setupContext.setup.discovery || {},
   });
   baseResult.diagnostics.push(...rawDiscovery.diagnostics);
   validateRequestedService(filters.serviceFilter, setupContext.setup.services || {}, rawDiscovery);
@@ -86,6 +89,12 @@ export async function discoverTests(options = {}) {
       services: resolved.services,
       suites: resolved.suites,
       files: resolved.files,
+      coverageGraph: buildCoverageGraph({
+        productDir,
+        repoDiscovery: setupContext.setup.discovery || {},
+        services: setupContext.setup.services || {},
+        discoveryFiles: rawDiscovery.files || [],
+      }),
       },
       productDir
     );
@@ -102,6 +111,12 @@ export async function discoverTests(options = {}) {
     services: rawOnly.services,
     suites: rawOnly.suites,
     files: rawOnly.files,
+    coverageGraph: buildCoverageGraph({
+      productDir,
+      repoDiscovery: setupContext.setup.discovery || {},
+      services: setupContext.setup.services || {},
+      discoveryFiles: rawDiscovery.files || [],
+    }),
     },
     productDir
   );

package/lib/discovery/path-policy.mjs

@@ -0,0 +1,106 @@
+import fs from "fs";
+import path from "path";
+
+export const DEFAULT_DISCOVERY_EXCLUDES = Object.freeze([
+  ".cache",
+  ".git",
+  ".hg",
+  ".next",
+  ".nuxt",
+  ".playwright-browsers",
+  ".svn",
+  ".testkit",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report",
+  "test-results",
+]);
+
+export function normalizeDiscoveryConfig(value, { allowRoots = true } = {}) {
+  if (value == null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("testkit discovery config must be an object");
+  }
+
+  const normalized = {};
+  if (allowRoots && Object.prototype.hasOwnProperty.call(value, "roots")) {
+    normalized.roots = normalizeDiscoveryPathList(value.roots, "testkit discovery roots");
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "exclude")) {
+    normalized.exclude = normalizeDiscoveryPathList(value.exclude, "testkit discovery exclude");
+  }
+  return normalized;
+}
+
+export function mergeDiscoveryConfigs(...configs) {
+  const merged = {};
+  for (const config of configs.filter(Boolean)) {
+    if (Array.isArray(config.roots)) {
+      merged.roots = [...config.roots];
+    }
+    if (Array.isArray(config.exclude) && config.exclude.length > 0) {
+      merged.exclude = [...new Set([...(merged.exclude || []), ...config.exclude])];
+    }
+  }
+  return merged;
+}
+
+export function resolveDiscoveryRoots(baseDir, roots, defaultRoot = ".") {
+  const normalizedRoots = Array.isArray(roots) && roots.length > 0 ? roots : [defaultRoot];
+  const seen = new Set();
+  const resolved = [];
+
+  for (const root of normalizedRoots) {
+    const normalizedRoot = normalizeDiscoveryPath(root);
+    if (!normalizedRoot) continue;
+    const absolutePath = path.resolve(baseDir, normalizedRoot === "." ? "." : normalizedRoot);
+    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isDirectory()) continue;
+    if (seen.has(absolutePath)) continue;
+    seen.add(absolutePath);
+    resolved.push(absolutePath);
+  }
+
+  return resolved.sort((left, right) => left.localeCompare(right));
+}
+
+export function shouldExcludeDiscoveryPath(relativePath, exclude = []) {
+  const normalizedPath = normalizeDiscoveryPath(relativePath);
+  if (!normalizedPath || normalizedPath === ".") return false;
+  return exclude.some((pattern) => matchesDiscoveryPathPattern(normalizedPath, pattern));
+}
+
+export function normalizeDiscoveryPath(value) {
+  const normalized = String(value || "")
+    .trim()
+    .split(path.sep)
+    .join("/")
+    .replace(/^\.\/+/u, "")
+    .replace(/\/+/gu, "/")
+    .replace(/\/+$/u, "");
+  return normalized || ".";
+}
+
+function normalizeDiscoveryPathList(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array of relative paths`);
+  }
+  const normalized = value
+    .map((entry) => {
+      if (typeof entry !== "string" || entry.trim().length === 0) {
+        throw new Error(`${label} entries must be non-empty strings`);
+      }
+      if (path.isAbsolute(entry)) {
+        throw new Error(`${label} entries must be relative paths`);
+      }
+      return normalizeDiscoveryPath(entry);
+    })
+    .filter(Boolean);
+  return [...new Set(normalized)];
+}
+
+function matchesDiscoveryPathPattern(relativePath, pattern) {
+  return relativePath === pattern || relativePath.startsWith(`${pattern}/`);
+}

package/lib/discovery/path-policy.test.mjs

@@ -0,0 +1,65 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  mergeDiscoveryConfigs,
+  normalizeDiscoveryConfig,
+  resolveDiscoveryRoots,
+  shouldExcludeDiscoveryPath,
+} from "./path-policy.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("discovery path policy", () => {
+  it("normalizes roots and excludes as relative paths", () => {
+    expect(
+      normalizeDiscoveryConfig({
+        roots: ["./app/", "src/app"],
+        exclude: ["./coverage/", "dist"],
+      })
+    ).toEqual({
+      roots: ["app", "src/app"],
+      exclude: ["coverage", "dist"],
+    });
+  });
+
+  it("merges excludes without losing later roots", () => {
+    expect(
+      mergeDiscoveryConfigs(
+        { roots: ["src"], exclude: ["coverage"] },
+        { exclude: ["dist"] },
+        { roots: ["app"], exclude: ["test-results"] }
+      )
+    ).toEqual({
+      roots: ["app"],
+      exclude: ["coverage", "dist", "test-results"],
+    });
+  });
+
+  it("treats exclude paths as path prefixes rather than bare directory names", () => {
+    expect(shouldExcludeDiscoveryPath("coverage", ["coverage"])).toBe(true);
+    expect(shouldExcludeDiscoveryPath("coverage/report/index.html", ["coverage"])).toBe(true);
+    expect(shouldExcludeDiscoveryPath("app/coverage", ["coverage"])).toBe(false);
+    expect(shouldExcludeDiscoveryPath("src/app/coverage", ["coverage"])).toBe(false);
+  });
+
+  it("resolves only existing discovery roots", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-discovery-roots-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+    fs.mkdirSync(path.join(productDir, "app"), { recursive: true });
+    fs.mkdirSync(path.join(productDir, "src", "app"), { recursive: true });
+
+    const roots = resolveDiscoveryRoots(productDir, ["app", "missing", "src/app"]);
+    expect(roots).toEqual([
+      path.join(productDir, "app"),
+      path.join(productDir, "src", "app"),
+    ]);
+  });
+});

package/lib/setup/index.d.ts

@@ -106,22 +106,30 @@ export interface TestkitExecutionConfig {
   fileTimeoutSeconds?: number;
 }
 
+export interface BrowserServiceConfig {
+  origins?: string[];
+}
+
 export interface KnownFailureIssueValidationConfig {
   provider?: "github";
   mode?: "off" | "warn" | "error";
   cacheTtlSeconds?: number;
 }
 
+export interface DiscoveryConfig {
+  roots?: string[];
+  exclude?: string[];
+}
+
 export interface ServiceConfig {
   database?: LocalDatabaseConfig;
   databaseFrom?: string;
   dependsOn?: string[];
-  discovery?: {
-    roots?: string[];
-  };
+  discovery?: DiscoveryConfig;
   env?: Record<string, string>;
   envFile?: string;
   envFiles?: string[];
+  browser?: BrowserServiceConfig;
   local?: false | {
     baseUrl: string;
     cwd?: string;
@@ -137,6 +145,7 @@ export interface ServiceConfig {
 }
 
 export interface TestkitSetup {
+  discovery?: DiscoveryConfig;
   execution?: TestkitExecutionConfig;
   profiles?: {
     http?: Record<string, HttpSuiteConfig>;

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

@@ -0,0 +1,17 @@
+{
+  "name": "@elench/testkit-bridge",
+  "version": "0.1.59",
+  "description": "Browser bridge helpers for testkit",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@elench/testkit-protocol": "0.1.59"
+  },
+  "private": false
+}