@elench/testkit 0.1.62 → 0.1.63

package/lib/coverage/shared.mjs

@@ -9,6 +9,7 @@ export const HTTP_WRAPPER_METHODS = {
   patchJson: "PATCH",
   deleteJson: "DELETE",
 };
+export const DYNAMIC_SEGMENT_TOKEN = "__TESTKIT_DYNAMIC_SEGMENT__";
 
 export function createEmptyGraph() {
   return {
@@ -196,3 +197,69 @@ export function dedupeDataImports(entries) {
     return true;
   });
 }
+
+export function findMatchingApiRouteEntry(method, candidatePath, routeEntries = []) {
+  const normalizedMethod = String(method || "").trim().toUpperCase();
+  const normalizedCandidate = normalizeRequestPathCandidate(candidatePath);
+  if (!normalizedMethod || !normalizedCandidate) return null;
+
+  return [...routeEntries]
+    .filter((entry) => entry.method === normalizedMethod)
+    .sort(compareRouteSpecificity)
+    .find((entry) => routePatternMatchesCandidate(entry.requestPath, normalizedCandidate)) || null;
+}
+
+export function findMatchingRouteValue(candidateRoute, routeValues = []) {
+  const normalizedCandidate = normalizeRequestPathCandidate(candidateRoute);
+  if (!normalizedCandidate) return null;
+
+  return [...routeValues]
+    .sort((left, right) => compareRouteSpecificity({ requestPath: left }, { requestPath: right }))
+    .find((routeValue) => routePatternMatchesCandidate(routeValue, normalizedCandidate)) || null;
+}
+
+export function normalizeRequestPathCandidate(value) {
+  if (typeof value !== "string") return null;
+  const [withoutHash] = value.split("#");
+  const [withoutQuery] = withoutHash.split("?");
+  return normalizeRoute(withoutQuery || "/");
+}
+
+export function routePatternMatchesCandidate(patternPath, candidatePath) {
+  const normalizedPattern = normalizeRequestPathCandidate(patternPath);
+  const normalizedCandidate = normalizeRequestPathCandidate(candidatePath);
+  if (!normalizedPattern || !normalizedCandidate) return false;
+
+  const patternSegments = splitRouteSegments(normalizedPattern);
+  const candidateSegments = splitRouteSegments(normalizedCandidate);
+  if (patternSegments.length !== candidateSegments.length) return false;
+
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const patternSegment = patternSegments[index];
+    const candidateSegment = candidateSegments[index];
+    if (patternSegment === candidateSegment) continue;
+    if (isDynamicRouteSegment(patternSegment) && candidateSegment.length > 0) continue;
+    if (candidateSegment === DYNAMIC_SEGMENT_TOKEN && isDynamicRouteSegment(patternSegment)) continue;
+    return false;
+  }
+
+  return true;
+}
+
+export function isDynamicRouteSegment(segment) {
+  return /^\[[^/]+\]$/u.test(segment) || /^\[\.\.\.[^/]+\]$/u.test(segment) || /^\[\[\.\.\.[^/]+\]\]$/u.test(segment);
+}
+
+function splitRouteSegments(value) {
+  if (value === "/") return [];
+  return value.split("/").filter(Boolean);
+}
+
+function compareRouteSpecificity(left, right) {
+  const leftSegments = splitRouteSegments(left.requestPath || "");
+  const rightSegments = splitRouteSegments(right.requestPath || "");
+  const leftStaticSegments = leftSegments.filter((segment) => !isDynamicRouteSegment(segment)).length;
+  const rightStaticSegments = rightSegments.filter((segment) => !isDynamicRouteSegment(segment)).length;
+  if (leftStaticSegments !== rightStaticSegments) return rightStaticSegments - leftStaticSegments;
+  return rightSegments.length - leftSegments.length;
+}

package/lib/coverage/shared.test.mjs

@@ -1,8 +1,12 @@
 import { describe, expect, it } from "vitest";
 import {
+  DYNAMIC_SEGMENT_TOKEN,
   dedupeTargets,
+  findMatchingApiRouteEntry,
+  findMatchingRouteValue,
   modulePathKey,
   pageLabelFromRoute,
+  routePatternMatchesCandidate,
   toApiRequestPath,
   toSelectionType,
 } from "./shared.mjs";
@@ -36,4 +40,33 @@ describe("coverage shared helpers", () => {
     expect(toSelectionType("integration", "http")).toBe("int");
     expect(toSelectionType("ui", "playwright")).toBe("pw");
   });
+
+  it("matches dynamic API route patterns against concrete and template-like request paths", () => {
+    expect(routePatternMatchesCandidate("/api/projects/[projectId]/overview", "/api/projects/123/overview")).toBe(true);
+    expect(
+      routePatternMatchesCandidate(
+        "/api/projects/[projectId]/events",
+        `/api/projects/${DYNAMIC_SEGMENT_TOKEN}/events`
+      )
+    ).toBe(true);
+    expect(routePatternMatchesCandidate("/api/projects/[projectId]/events", "/api/projects/123/stats")).toBe(false);
+  });
+
+  it("prefers the most specific matching API route entry", () => {
+    const routeEntry = findMatchingApiRouteEntry("GET", "/api/projects/123/events", [
+      { method: "GET", requestPath: "/api/projects/[projectId]" },
+      { method: "GET", requestPath: "/api/projects/[projectId]/events" },
+    ]);
+
+    expect(routeEntry).toEqual({
+      method: "GET",
+      requestPath: "/api/projects/[projectId]/events",
+    });
+  });
+
+  it("matches dynamic page routes against discovered route patterns", () => {
+    expect(
+      findMatchingRouteValue(`/projects/${DYNAMIC_SEGMENT_TOKEN}`, ["/projects/[projectId]", "/projects"])
+    ).toBe("/projects/[projectId]");
+  });
 });

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./src/index.mjs",
@@ -11,7 +11,7 @@
     "src/"
   ],
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.62"
+    "@elench/testkit-protocol": "0.1.63"
   },
   "private": false
 }

package/node_modules/@elench/testkit-bridge/src/index.mjs

@@ -269,6 +269,11 @@ function buildGraphProjection(context, page, matchedServiceName) {
     .filter((node) => node?.kind === "ui_surface");
   const pageReachableNodeIds = collectReachableNodeIds(pageNode.id, outgoing);
 
+  const surfaceReachableEntries = surfaceNodes.map((surfaceNode) => ({
+    surfaceNode,
+    reachableNodeIds: collectReachableNodeIds(surfaceNode.id, outgoing),
+  }));
+
   if (surfaceNodes.length === 0) {
     const relevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], pageReachableNodeIds));
     return buildPageLevelProjection({
@@ -285,8 +290,9 @@ function buildGraphProjection(context, page, matchedServiceName) {
   const coverage = [];
   const failures = [];
 
-  for (const surfaceNode of surfaceNodes.sort((left, right) => left.id.localeCompare(right.id))) {
-    const surfaceReachableNodeIds = collectReachableNodeIds(surfaceNode.id, outgoing);
+  for (const { surfaceNode, reachableNodeIds: surfaceReachableNodeIds } of surfaceReachableEntries.sort((left, right) =>
+    left.surfaceNode.id.localeCompare(right.surfaceNode.id)
+  )) {
     const relevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], surfaceReachableNodeIds));
     const supportingTests = relevantEvidence
       .map((entry) => buildSupportingTestRef(entry, discoveryByFile, context.runArtifact))
@@ -342,6 +348,22 @@ function buildGraphProjection(context, page, matchedServiceName) {
     });
   }
 
+  const routeLevelNodeIds = collectRouteLevelNodeIds(pageReachableNodeIds, surfaceReachableEntries);
+  if (routeLevelNodeIds.size > 0) {
+    const routeRelevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], routeLevelNodeIds));
+    const pageProjection = buildPageLevelProjection({
+      pageNode,
+      nodeById,
+      relevantEvidence: routeRelevantEvidence,
+      pageReachableNodeIds: routeLevelNodeIds,
+      discoveryByFile,
+      failureByFile,
+      runArtifact: context.runArtifact,
+    });
+    coverage.unshift(...pageProjection.coverage);
+    failures.unshift(...pageProjection.failures);
+  }
+
   return { coverage, failures };
 }
 
@@ -417,6 +439,16 @@ function collectReachableNodeIds(startNodeId, outgoing) {
   return visited;
 }
 
+function collectRouteLevelNodeIds(pageReachableNodeIds, surfaceReachableEntries) {
+  const routeLevelNodeIds = new Set(pageReachableNodeIds);
+  for (const { reachableNodeIds } of surfaceReachableEntries) {
+    for (const nodeId of reachableNodeIds) {
+      routeLevelNodeIds.delete(nodeId);
+    }
+  }
+  return routeLevelNodeIds;
+}
+
 function collectViaNodes(evidenceEntries, reachableNodeIds, nodeById, excludedNodeIds = new Set()) {
   const nodes = new Map();
   for (const entry of evidenceEntries) {

package/node_modules/@elench/testkit-bridge/src/index.test.mjs

@@ -161,6 +161,163 @@ const context = {
   },
 };
 
+const routeLevelContext = {
+  product: {
+    name: "dashboard",
+    directory: "/tmp/dashboard",
+  },
+  services: [
+    {
+      name: "dashboard",
+      baseUrl: "http://localhost:3000",
+      origin: "http://localhost:3000",
+    },
+  ],
+  discovery: {
+    files: [
+      {
+        path: "__testkit__/projects/projects.int.testkit.ts",
+        displayName: "Projects",
+        service: "dashboard",
+        suiteName: "projects",
+        selectionType: "int",
+        framework: "k6",
+        skipped: false,
+      },
+    ],
+    coverageGraph: {
+      schemaVersion: 1,
+      nodes: [
+        {
+          id: "page_view:dashboard:/projects",
+          kind: "page_view",
+          service: "dashboard",
+          label: "Projects",
+          route: "/projects",
+          filePath: "src/app/projects/page.tsx",
+        },
+        {
+          id: "ui_surface:dashboard:/projects:project-create-button",
+          kind: "ui_surface",
+          service: "dashboard",
+          label: "Create Project",
+          route: "/projects",
+          filePath: "src/app/projects/page.tsx",
+          target: { kind: "testId", value: "project-create-button", confidence: "high" },
+        },
+        {
+          id: "ui_action:dashboard:/projects:handleCreate",
+          kind: "ui_action",
+          service: "dashboard",
+          label: "handleCreate",
+          route: "/projects",
+          filePath: "src/app/projects/page.tsx",
+        },
+        {
+          id: "client_request:dashboard:provider:GET:/api/projects",
+          kind: "client_request",
+          service: "dashboard",
+          label: "GET /api/projects",
+          route: "/projects",
+          method: "GET",
+          path: "/api/projects",
+          filePath: "src/components/project-context.tsx",
+        },
+        {
+          id: "client_request:dashboard:projects:POST:/api/projects",
+          kind: "client_request",
+          service: "dashboard",
+          label: "POST /api/projects",
+          route: "/projects",
+          method: "POST",
+          path: "/api/projects",
+          filePath: "src/app/projects/page.tsx",
+        },
+        {
+          id: "api_route:dashboard:GET:/api/projects",
+          kind: "api_route",
+          service: "dashboard",
+          label: "GET /api/projects",
+          route: "/projects",
+          method: "GET",
+          path: "/api/projects",
+          filePath: "src/app/api/projects/route.ts",
+        },
+        {
+          id: "api_route:dashboard:POST:/api/projects",
+          kind: "api_route",
+          service: "dashboard",
+          label: "POST /api/projects",
+          route: "/projects",
+          method: "POST",
+          path: "/api/projects",
+          filePath: "src/app/api/projects/route.ts",
+        },
+      ],
+      edges: [
+        {
+          id: "contains:page_view:dashboard:/projects:ui_surface:dashboard:/projects:project-create-button",
+          kind: "contains",
+          from: "page_view:dashboard:/projects",
+          to: "ui_surface:dashboard:/projects:project-create-button",
+        },
+        {
+          id: "triggers:ui_surface:dashboard:/projects:project-create-button:ui_action:dashboard:/projects:handleCreate",
+          kind: "triggers",
+          from: "ui_surface:dashboard:/projects:project-create-button",
+          to: "ui_action:dashboard:/projects:handleCreate",
+        },
+        {
+          id: "requests:page_view:dashboard:/projects:client_request:dashboard:provider:GET:/api/projects",
+          kind: "requests",
+          from: "page_view:dashboard:/projects",
+          to: "client_request:dashboard:provider:GET:/api/projects",
+        },
+        {
+          id: "requests:ui_action:dashboard:/projects:handleCreate:client_request:dashboard:projects:POST:/api/projects",
+          kind: "requests",
+          from: "ui_action:dashboard:/projects:handleCreate",
+          to: "client_request:dashboard:projects:POST:/api/projects",
+        },
+        {
+          id: "handles:client_request:dashboard:provider:GET:/api/projects:api_route:dashboard:GET:/api/projects",
+          kind: "handles",
+          from: "client_request:dashboard:provider:GET:/api/projects",
+          to: "api_route:dashboard:GET:/api/projects",
+        },
+        {
+          id: "handles:client_request:dashboard:projects:POST:/api/projects:api_route:dashboard:POST:/api/projects",
+          kind: "handles",
+          from: "client_request:dashboard:projects:POST:/api/projects",
+          to: "api_route:dashboard:POST:/api/projects",
+        },
+      ],
+      evidence: [
+        {
+          id: "evidence:dashboard:__testkit__/projects/projects.int.testkit.ts",
+          source: "convention",
+          confidence: "high",
+          service: "dashboard",
+          suiteName: "projects",
+          selectionType: "int",
+          framework: "k6",
+          testFilePath: "__testkit__/projects/projects.int.testkit.ts",
+          coveredNodeIds: [
+            "api_route:dashboard:GET:/api/projects",
+            "api_route:dashboard:POST:/api/projects",
+          ],
+          details: {
+            route: "/projects",
+            requestPaths: ["/api/projects"],
+          },
+        },
+      ],
+      diagnostics: [],
+    },
+  },
+  runArtifact: null,
+};
+
 describe("testkit bridge", () => {
   it("matches pages against service base URLs", () => {
     expect(buildMatchResponse(context, "http://localhost:3000/coverage")).toMatchObject({
@@ -177,46 +334,76 @@ describe("testkit bridge", () => {
       summary: {
         failureState: "failing",
         coverageState: "covered",
-        relatedFailureCount: 1,
-        relatedCoverageCount: 1,
+        relatedFailureCount: 2,
+        relatedCoverageCount: 2,
         coverageBreakdown: {
-          direct: 0,
+          direct: 1,
           indirect: 0,
           mixed: 1,
         },
       },
-      failures: [
-        {
+      failures: expect.arrayContaining([
+        expect.objectContaining({
+          kind: "page_view",
+          label: "Coverage",
+        }),
+        expect.objectContaining({
           kind: "ui_surface",
           label: "Refresh overlay",
           importance: "high",
           reason: "Refresh overlay is implicated by 1 failing test.",
           targets: [{ kind: "testId", value: "coverage-refresh-button", confidence: "high" }],
           failedTests: [
-            {
+            expect.objectContaining({
               filePath: "app/coverage/__testkit__/coverage.pw.testkit.ts",
               type: "pw",
-            },
+            }),
           ],
-        },
-      ],
-      coverage: [
-        {
+        }),
+      ]),
+      coverage: expect.arrayContaining([
+        expect.objectContaining({
+          kind: "page_view",
+          label: "Coverage",
+          supportKind: "direct",
+        }),
+        expect.objectContaining({
           kind: "ui_surface",
           label: "Refresh overlay",
           importance: "high",
           supportKind: "mixed",
           targets: [{ kind: "testId", value: "coverage-refresh-button", confidence: "high" }],
           supportingTests: [
-            {
+            expect.objectContaining({
               filePath: "app/coverage/__testkit__/coverage.pw.testkit.ts",
-            },
-            {
+            }),
+            expect.objectContaining({
               filePath: "app/api/coverage/__testkit__/coverage.int.testkit.ts",
-            },
+            }),
           ],
-        },
-      ],
+        }),
+      ]),
+    });
+  });
+
+  it("retains route-level coverage when support comes from page-owned requests outside any surfaced control", () => {
+    expect(buildPageOverlayResponse(routeLevelContext, "http://localhost:3000/projects")).toMatchObject({
+      summary: {
+        coverageState: "covered",
+        relatedCoverageCount: 2,
+      },
+      coverage: expect.arrayContaining([
+        expect.objectContaining({
+          kind: "page_view",
+          label: "Projects",
+          supportKind: "indirect",
+        }),
+        expect.objectContaining({
+          kind: "ui_surface",
+          label: "Create Project",
+          supportKind: "indirect",
+        }),
+      ]),
     });
   });
 });

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./src/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "workspaces": [
@@ -59,8 +59,8 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@elench/testkit-bridge": "0.1.62",
-    "@elench/testkit-protocol": "0.1.62",
+    "@elench/testkit-bridge": "0.1.63",
+    "@elench/testkit-protocol": "0.1.63",
     "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",