@elench/testkit 0.1.57 → 0.1.58

package/node_modules/@elench/testkit-protocol/src/index.d.ts

@@ -0,0 +1,204 @@
+export declare const TESTKIT_BROWSER_PROTOCOL_VERSION = 1;
+export declare const TESTKIT_COVERAGE_GRAPH_VERSION = 1;
+
+export type BrowserTargetKind = "testId" | "role" | "text" | "css" | "xpath" | "component";
+export type BrowserConfidence = "low" | "medium" | "high";
+export type BrowserFailureState = "failing" | "healthy" | "unavailable";
+export type BrowserCoverageState = "covered" | "missing" | "unavailable";
+
+export type CoverageNodeKind =
+  | "page_view"
+  | "ui_surface"
+  | "ui_action"
+  | "client_request"
+  | "api_route"
+  | "server_action"
+  | "server_capability"
+  | "data_capability"
+  | "test_file";
+
+export type CoverageEdgeKind =
+  | "contains"
+  | "renders"
+  | "triggers"
+  | "requests"
+  | "handles"
+  | "delegates_to"
+  | "covers";
+
+export type CoverageEvidenceSource = "convention" | "static" | "runtime";
+
+export interface BrowserTarget {
+  kind: BrowserTargetKind;
+  value: string;
+  label?: string;
+  confidence?: BrowserConfidence;
+}
+
+export interface BrowserMetadata {
+  label?: string;
+  origins?: string[];
+  routes?: string[];
+  targets?: BrowserTarget[];
+}
+
+export interface BrowserMetadataDocument {
+  schemaVersion: number;
+  browser: BrowserMetadata;
+}
+
+export interface CoverageGraphNode {
+  id: string;
+  kind: CoverageNodeKind;
+  service: string;
+  label: string;
+  filePath?: string;
+  route?: string;
+  method?: string;
+  path?: string;
+  target?: BrowserTarget | null;
+  metadata?: Record<string, string | number | boolean | null>;
+}
+
+export interface CoverageGraphEdge {
+  id: string;
+  kind: CoverageEdgeKind;
+  from: string;
+  to: string;
+  confidence?: BrowserConfidence;
+  metadata?: Record<string, string | number | boolean | null>;
+}
+
+export interface CoverageEvidence {
+  id: string;
+  source: CoverageEvidenceSource;
+  confidence?: BrowserConfidence;
+  service: string;
+  suiteName: string;
+  selectionType: string;
+  framework: string;
+  testFilePath: string;
+  coveredNodeIds: string[];
+  details?: {
+    requestPaths?: string[];
+    route?: string;
+  };
+}
+
+export interface CoverageGraph {
+  schemaVersion: number;
+  nodes: CoverageGraphNode[];
+  edges: CoverageGraphEdge[];
+  evidence: CoverageEvidence[];
+}
+
+export interface BridgeProductRef {
+  name: string;
+  directory: string;
+}
+
+export interface BridgeServiceRef {
+  name: string;
+  baseUrl: string;
+  origin: string;
+}
+
+export interface BrowserMatchResponse {
+  protocolVersion: number;
+  url: string;
+  origin: string;
+  route: string;
+  matched: boolean;
+  product: BridgeProductRef;
+  service: BridgeServiceRef | null;
+}
+
+export interface BridgeRunSummary {
+  artifactAvailable: boolean;
+  generatedAt: string | null;
+  status: string | null;
+}
+
+export interface BridgeSupportingTestRef {
+  service: string;
+  suite: string;
+  type: string;
+  framework: string;
+  filePath: string;
+  label: string;
+  status?: "passed" | "failed" | "skipped" | "not_run";
+  error?: string | null;
+}
+
+export interface BridgeCoverageViaNodeRef {
+  id: string;
+  kind: CoverageNodeKind;
+  label: string;
+  route?: string;
+  method?: string;
+  path?: string;
+}
+
+export interface FailureOverlayEntry {
+  id: string;
+  kind: CoverageNodeKind;
+  label: string;
+  service: string;
+  route?: string | null;
+  targets: BrowserTarget[];
+  failedTests: BridgeSupportingTestRef[];
+  viaNodes: BridgeCoverageViaNodeRef[];
+}
+
+export interface CoverageOverlayEntry {
+  id: string;
+  kind: CoverageNodeKind;
+  label: string;
+  service: string;
+  route?: string | null;
+  targets: BrowserTarget[];
+  supportingTests: BridgeSupportingTestRef[];
+  viaNodes: BridgeCoverageViaNodeRef[];
+  confidence: BrowserConfidence;
+}
+
+export interface PageOverlayResponse {
+  protocolVersion: number;
+  page: {
+    url: string;
+    origin: string;
+    route: string;
+  };
+  match: BrowserMatchResponse;
+  run: BridgeRunSummary;
+  summary: {
+    failureState: BrowserFailureState;
+    coverageState: BrowserCoverageState;
+    relatedFailureCount: number;
+    relatedCoverageCount: number;
+  };
+  failures: FailureOverlayEntry[];
+  coverage: CoverageOverlayEntry[];
+}
+
+export interface BridgeErrorResponse {
+  protocolVersion: number;
+  error: {
+    code: string;
+    message: string;
+  };
+}
+
+export declare function normalizeBrowserTarget(value: unknown): BrowserTarget | null;
+export declare function normalizeBrowserMetadata(value: unknown): BrowserMetadata | null;
+export declare function normalizeBrowserMetadataDocument(value: unknown): BrowserMetadataDocument | null;
+export declare function normalizeCoverageGraphNode(value: unknown): CoverageGraphNode | null;
+export declare function normalizeCoverageGraphEdge(value: unknown): CoverageGraphEdge | null;
+export declare function normalizeCoverageEvidence(value: unknown): CoverageEvidence | null;
+export declare function normalizeCoverageGraph(value: unknown): CoverageGraph | null;
+export declare function normalizePageOverlayResponse(value: unknown): PageOverlayResponse | null;
+export declare function isPageOverlayResponse(value: unknown): value is PageOverlayResponse;
+export declare function createBridgeErrorResponse(
+  code: string,
+  message: string
+): BridgeErrorResponse;

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

@@ -0,0 +1,245 @@
+export const TESTKIT_BROWSER_PROTOCOL_VERSION = 1;
+export const TESTKIT_COVERAGE_GRAPH_VERSION = 1;
+
+const TARGET_KINDS = new Set(["testId", "role", "text", "css", "xpath", "component"]);
+const CONFIDENCE_LEVELS = new Set(["low", "medium", "high"]);
+const FAILURE_STATES = new Set(["failing", "healthy", "unavailable"]);
+const COVERAGE_STATES = new Set(["covered", "missing", "unavailable"]);
+const NODE_KINDS = new Set([
+  "page_view",
+  "ui_surface",
+  "ui_action",
+  "client_request",
+  "api_route",
+  "server_action",
+  "server_capability",
+  "data_capability",
+  "test_file",
+]);
+const EDGE_KINDS = new Set([
+  "contains",
+  "renders",
+  "triggers",
+  "requests",
+  "handles",
+  "delegates_to",
+  "covers",
+]);
+const EVIDENCE_SOURCES = new Set(["convention", "static", "runtime"]);
+
+export function normalizeBrowserTarget(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const kind = normalizeOptionalString(value.kind);
+  const targetValue = normalizeOptionalString(value.value);
+  if (!kind || !TARGET_KINDS.has(kind) || !targetValue) return null;
+  const label = normalizeOptionalString(value.label);
+  const confidence = normalizeOptionalString(value.confidence);
+  return {
+    kind,
+    value: targetValue,
+    ...(label ? { label } : {}),
+    ...(confidence && CONFIDENCE_LEVELS.has(confidence) ? { confidence } : {}),
+  };
+}
+
+export function normalizeBrowserMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const label = normalizeOptionalString(value.label);
+  const origins = normalizeStringArray(value.origins);
+  const routes = normalizeStringArray(value.routes);
+  const targets = Array.isArray(value.targets) ? value.targets.map(normalizeBrowserTarget).filter(Boolean) : [];
+  if (!label && origins.length === 0 && routes.length === 0 && targets.length === 0) {
+    return null;
+  }
+  return {
+    ...(label ? { label } : {}),
+    ...(origins.length > 0 ? { origins } : {}),
+    ...(routes.length > 0 ? { routes } : {}),
+    ...(targets.length > 0 ? { targets } : {}),
+  };
+}
+
+export function normalizeBrowserMetadataDocument(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const schemaVersion =
+    Number.isInteger(value.schemaVersion) && value.schemaVersion > 0
+      ? value.schemaVersion
+      : TESTKIT_BROWSER_PROTOCOL_VERSION;
+  const browser = normalizeBrowserMetadata(value.browser);
+  if (!browser) return null;
+  return {
+    schemaVersion,
+    browser,
+  };
+}
+
+export function normalizeCoverageGraphNode(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const id = normalizeOptionalString(value.id);
+  const kind = normalizeOptionalString(value.kind);
+  const service = normalizeOptionalString(value.service);
+  const label = normalizeOptionalString(value.label);
+  if (!id || !kind || !NODE_KINDS.has(kind) || !service || !label) return null;
+  const filePath = normalizeOptionalString(value.filePath);
+  const route = normalizeOptionalString(value.route);
+  const method = normalizeOptionalString(value.method);
+  const path = normalizeOptionalString(value.path);
+  const target = normalizeBrowserTarget(value.target);
+  const metadata = normalizeMetadataRecord(value.metadata);
+  return {
+    id,
+    kind,
+    service,
+    label,
+    ...(filePath ? { filePath } : {}),
+    ...(route ? { route } : {}),
+    ...(method ? { method } : {}),
+    ...(path ? { path } : {}),
+    ...(target ? { target } : {}),
+    ...(metadata ? { metadata } : {}),
+  };
+}
+
+export function normalizeCoverageGraphEdge(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const id = normalizeOptionalString(value.id);
+  const kind = normalizeOptionalString(value.kind);
+  const from = normalizeOptionalString(value.from);
+  const to = normalizeOptionalString(value.to);
+  if (!id || !kind || !EDGE_KINDS.has(kind) || !from || !to) return null;
+  const confidence = normalizeOptionalString(value.confidence);
+  const metadata = normalizeMetadataRecord(value.metadata);
+  return {
+    id,
+    kind,
+    from,
+    to,
+    ...(confidence && CONFIDENCE_LEVELS.has(confidence) ? { confidence } : {}),
+    ...(metadata ? { metadata } : {}),
+  };
+}
+
+export function normalizeCoverageEvidence(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const id = normalizeOptionalString(value.id);
+  const source = normalizeOptionalString(value.source);
+  const service = normalizeOptionalString(value.service);
+  const suiteName = normalizeOptionalString(value.suiteName);
+  const selectionType = normalizeOptionalString(value.selectionType);
+  const framework = normalizeOptionalString(value.framework);
+  const testFilePath = normalizeOptionalString(value.testFilePath);
+  const coveredNodeIds = normalizeStringArray(value.coveredNodeIds);
+  if (
+    !id ||
+    !source ||
+    !EVIDENCE_SOURCES.has(source) ||
+    !service ||
+    !suiteName ||
+    !selectionType ||
+    !framework ||
+    !testFilePath ||
+    coveredNodeIds.length === 0
+  ) {
+    return null;
+  }
+  const confidence = normalizeOptionalString(value.confidence);
+  const details = normalizeEvidenceDetails(value.details);
+  return {
+    id,
+    source,
+    service,
+    suiteName,
+    selectionType,
+    framework,
+    testFilePath,
+    coveredNodeIds,
+    ...(confidence && CONFIDENCE_LEVELS.has(confidence) ? { confidence } : {}),
+    ...(details ? { details } : {}),
+  };
+}
+
+export function normalizeCoverageGraph(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const schemaVersion =
+    Number.isInteger(value.schemaVersion) && value.schemaVersion > 0
+      ? value.schemaVersion
+      : TESTKIT_COVERAGE_GRAPH_VERSION;
+  const nodes = Array.isArray(value.nodes) ? value.nodes.map(normalizeCoverageGraphNode).filter(Boolean) : [];
+  const edges = Array.isArray(value.edges) ? value.edges.map(normalizeCoverageGraphEdge).filter(Boolean) : [];
+  const evidence = Array.isArray(value.evidence)
+    ? value.evidence.map(normalizeCoverageEvidence).filter(Boolean)
+    : [];
+  if (nodes.length === 0) return null;
+  return {
+    schemaVersion,
+    nodes,
+    edges,
+    evidence,
+  };
+}
+
+export function isPageOverlayResponse(value) {
+  return Boolean(normalizePageOverlayResponse(value));
+}
+
+export function normalizePageOverlayResponse(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.protocolVersion !== TESTKIT_BROWSER_PROTOCOL_VERSION) return null;
+  if (!value.page || typeof value.page !== "object") return null;
+  if (!value.match || typeof value.match !== "object") return null;
+  if (!value.summary || typeof value.summary !== "object") return null;
+  if (!Array.isArray(value.coverage) || !Array.isArray(value.failures)) return null;
+  if (!FAILURE_STATES.has(value.summary.failureState)) return null;
+  if (!COVERAGE_STATES.has(value.summary.coverageState)) return null;
+  return value;
+}
+
+export function createBridgeErrorResponse(code, message) {
+  return {
+    protocolVersion: TESTKIT_BROWSER_PROTOCOL_VERSION,
+    error: {
+      code,
+      message,
+    },
+  };
+}
+
+function normalizeEvidenceDetails(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const requestPaths = normalizeStringArray(value.requestPaths);
+  const route = normalizeOptionalString(value.route);
+  if (requestPaths.length === 0 && !route) return null;
+  return {
+    ...(requestPaths.length > 0 ? { requestPaths } : {}),
+    ...(route ? { route } : {}),
+  };
+}
+
+function normalizeMetadataRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const normalized = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const normalizedKey = normalizeOptionalString(key);
+    if (!normalizedKey) continue;
+    if (
+      entry === null ||
+      typeof entry === "string" ||
+      typeof entry === "number" ||
+      typeof entry === "boolean"
+    ) {
+      normalized[normalizedKey] = entry;
+    }
+  }
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(normalizeOptionalString).filter(Boolean);
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}

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

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import {
+  TESTKIT_BROWSER_PROTOCOL_VERSION,
+  TESTKIT_COVERAGE_GRAPH_VERSION,
+  isPageOverlayResponse,
+  normalizeBrowserTarget,
+  normalizeCoverageEvidence,
+  normalizeCoverageGraph,
+  normalizeCoverageGraphEdge,
+  normalizeCoverageGraphNode,
+} from "./index.mjs";
+
+describe("testkit browser protocol", () => {
+  it("normalizes browser targets", () => {
+    expect(
+      normalizeBrowserTarget({
+        kind: "testId",
+        value: "coverage-refresh-button",
+        confidence: "high",
+      })
+    ).toEqual({
+      kind: "testId",
+      value: "coverage-refresh-button",
+      confidence: "high",
+    });
+  });
+
+  it("normalizes coverage graph nodes and edges", () => {
+    expect(
+      normalizeCoverageGraphNode({
+        id: "page_view:web:/coverage",
+        kind: "page_view",
+        service: "web",
+        label: "Coverage",
+        route: "/coverage",
+      })
+    ).toEqual({
+      id: "page_view:web:/coverage",
+      kind: "page_view",
+      service: "web",
+      label: "Coverage",
+      route: "/coverage",
+    });
+
+    expect(
+      normalizeCoverageGraphEdge({
+        id: "edge-1",
+        kind: "requests",
+        from: "page_view:web:/coverage",
+        to: "client_request:web:/api/coverage",
+        confidence: "high",
+      })
+    ).toEqual({
+      id: "edge-1",
+      kind: "requests",
+      from: "page_view:web:/coverage",
+      to: "client_request:web:/api/coverage",
+      confidence: "high",
+    });
+  });
+
+  it("normalizes positive coverage evidence", () => {
+    expect(
+      normalizeCoverageEvidence({
+        id: "evidence-1",
+        source: "convention",
+        confidence: "high",
+        service: "web",
+        suiteName: "coverage",
+        selectionType: "pw",
+        framework: "playwright",
+        testFilePath: "app/__testkit__/coverage/home.pw.testkit.ts",
+        coveredNodeIds: ["page_view:web:/coverage"],
+        details: {
+          route: "/coverage",
+          requestPaths: ["/api/coverage"],
+        },
+      })
+    ).toEqual({
+      id: "evidence-1",
+      source: "convention",
+      confidence: "high",
+      service: "web",
+      suiteName: "coverage",
+      selectionType: "pw",
+      framework: "playwright",
+      testFilePath: "app/__testkit__/coverage/home.pw.testkit.ts",
+      coveredNodeIds: ["page_view:web:/coverage"],
+      details: {
+        route: "/coverage",
+        requestPaths: ["/api/coverage"],
+      },
+    });
+  });
+
+  it("normalizes graph payloads", () => {
+    expect(
+      normalizeCoverageGraph({
+        schemaVersion: TESTKIT_COVERAGE_GRAPH_VERSION,
+        nodes: [
+          {
+            id: "page_view:web:/coverage",
+            kind: "page_view",
+            service: "web",
+            label: "Coverage",
+            route: "/coverage",
+          },
+        ],
+        edges: [],
+        evidence: [],
+      })
+    ).toEqual({
+      schemaVersion: TESTKIT_COVERAGE_GRAPH_VERSION,
+      nodes: [
+        {
+          id: "page_view:web:/coverage",
+          kind: "page_view",
+          service: "web",
+          label: "Coverage",
+          route: "/coverage",
+        },
+      ],
+      edges: [],
+      evidence: [],
+    });
+  });
+
+  it("recognizes valid page overlay responses", () => {
+    expect(
+      isPageOverlayResponse({
+        protocolVersion: TESTKIT_BROWSER_PROTOCOL_VERSION,
+        page: { url: "http://localhost:3000/coverage", origin: "http://localhost:3000", route: "/coverage" },
+        match: {
+          protocolVersion: TESTKIT_BROWSER_PROTOCOL_VERSION,
+          url: "http://localhost:3000/coverage",
+          origin: "http://localhost:3000",
+          route: "/coverage",
+          matched: true,
+          product: { name: "web", directory: "/tmp/web" },
+          service: { name: "web", baseUrl: "http://localhost:3000", origin: "http://localhost:3000" },
+        },
+        run: { artifactAvailable: true, generatedAt: null, status: "failed" },
+        summary: {
+          failureState: "failing",
+          coverageState: "covered",
+          relatedFailureCount: 1,
+          relatedCoverageCount: 1,
+        },
+        failures: [],
+        coverage: [],
+      })
+    ).toBe(true);
+  });
+});

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.57",
+  "version": "0.1.58",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "types": "./lib/index.d.ts",
   "exports": {
     ".": {
@@ -38,7 +41,7 @@
   },
   "scripts": {
     "test": "vitest run",
-    "test:unit": "vitest run lib",
+    "test:unit": "vitest run lib packages",
     "test:integration": "vitest run test/integration",
     "test:system": "vitest run test/system --passWithNoTests"
   },
@@ -47,11 +50,17 @@
     "lib/",
     "vendor/"
   ],
+  "bundleDependencies": [
+    "@elench/testkit-bridge",
+    "@elench/testkit-protocol"
+  ],
   "devDependencies": {
     "@playwright/test": "^1.52.0",
     "vitest": "^3.2.4"
   },
   "dependencies": {
+    "@elench/testkit-bridge": "0.1.58",
+    "@elench/testkit-protocol": "0.1.58",
     "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",