@kkeve/suite 0.0.15 → 0.0.17

package/dist/engine-cypress/pageOps.js

@@ -0,0 +1,439 @@
+"use strict";
+/**
+ * pageOps — 注入 AUT 的「操作原语 + 网络记录」源码
+ *
+ * 与 locatorSource.ts 同样以「自包含源码字符串」形式注入：isolated world 里的
+ * 函数无法闭包引用 bundle 变量，只能整段送过去求值。
+ *
+ * 职责边界：
+ *   locatorSource → 定位（ElementRef / hop 链 → 元素集合）
+ *   pageOps       → 动作与读取（点击/输入/拖拽/文本/可见性/属性/滚动）
+ *   netLog        → fetch/XHR 记录，支撑 waitForResponse 的软等待门
+ *
+ * 交互走原生 DOM 事件（探针已验证 React 合成事件能正常响应），
+ * 与 Playwright 的 locator click 在「触发应用逻辑」这一层语义等价。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageOpsSource = pageOpsSource;
+exports.netLogSource = netLogSource;
+exports.bootstrapSource = bootstrapSource;
+exports.diagnosticsSource = diagnosticsSource;
+function pageOpsSource() {
+    return `(() => {
+  "use strict";
+  if (window.__keveOpsSource === "v1") return "cached";
+
+  function locator() {
+    if (!window.__keveLocator) throw new Error("[keve] locator 未注入");
+    return window.__keveLocator;
+  }
+
+  /** refs → 末端元素集合（定位语义与 PlaywrightEngine.resolveChain 对齐） */
+  function resolve(refs) {
+    if (!refs || !refs.length) throw new Error("[keve] 缺少元素定位参数");
+    var res = locator().resolveRefChain(refs);
+    return (res && res.els) || [];
+  }
+
+  function first(refs) {
+    var els = resolve(refs);
+    if (!els.length) throw new Error("[keve] 元素未找到: " + JSON.stringify(refs).slice(0, 300));
+    return els[0];
+  }
+
+  function isVisible(el) {
+    if (!el || !el.isConnected) return false;
+    var rect = el.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) return false;
+    var style = window.getComputedStyle(el);
+    if (!style) return true;
+    if (style.visibility === "hidden" || style.display === "none") return false;
+    if (Number(style.opacity) === 0) return false;
+    return true;
+  }
+
+  /** 原生事件序列：点击/双击/悬停都走真实 MouseEvent，保证 React 合成事件生效 */
+  function mouse(el, type, detail) {
+    var rect = el.getBoundingClientRect();
+    var init = {
+      bubbles: true, cancelable: true, composed: true, view: window,
+      detail: detail || 1, button: 0,
+      clientX: Math.round(rect.left + rect.width / 2),
+      clientY: Math.round(rect.top + rect.height / 2),
+    };
+    el.dispatchEvent(new MouseEvent(type, init));
+  }
+
+  function clickEl(el, dbl) {
+    el.scrollIntoView({ block: "center", inline: "center" });
+    el.focus && el.focus();
+    mouse(el, "mousedown");
+    mouse(el, "mouseup");
+    if (typeof el.click === "function") el.click();
+    else mouse(el, "click");
+    mouse(el, "click");
+    if (dbl) {
+      mouse(el, "mousedown", 2);
+      mouse(el, "mouseup", 2);
+      mouse(el, "dblclick", 2);
+    }
+  }
+
+  function setValue(el, text) {
+    var value = text == null ? "" : String(text);
+    el.scrollIntoView({ block: "center", inline: "center" });
+    el.focus && el.focus();
+    if (el.isContentEditable) {
+      el.textContent = value;
+      el.dispatchEvent(new InputEvent("input", { bubbles: true, data: value }));
+      return;
+    }
+    var proto = el instanceof HTMLTextAreaElement
+      ? HTMLTextAreaElement.prototype
+      : (el instanceof HTMLSelectElement ? HTMLSelectElement.prototype : HTMLInputElement.prototype);
+    var desc = Object.getOwnPropertyDescriptor(proto, "value");
+    if (desc && desc.set) desc.set.call(el, value);
+    else el.value = value;
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+
+  function textOf(el) {
+    if (!el) return "";
+    var t = el.value != null && String(el.value) !== "" ? String(el.value) : String(el.textContent || "");
+    return t.replace(/\\s+/g, " ").trim();
+  }
+
+  function attrOf(el, name) {
+    if (!el) return null;
+    return el.getAttribute(name);
+  }
+
+  function classList(el) {
+    return el ? String(el.getAttribute("class") || "") : "";
+  }
+
+  function dragEl(src, dst) {
+    var dt = null;
+    try { dt = new DataTransfer(); } catch (e) { dt = null; }
+    var types = ["dragstart", "dragenter", "dragover", "drop", "dragend"];
+    for (var i = 0; i < types.length; i += 1) {
+      var target = (types[i] === "dragstart" || types[i] === "dragend") ? src : dst;
+      var ev = new DragEvent(types[i], { bubbles: true, cancelable: true, dataTransfer: dt });
+      target.dispatchEvent(ev);
+    }
+  }
+
+  window.__keveOps = {
+    version: "v1",
+    resolve: resolve,
+    count: function (refs) { return resolve(refs).length; },
+    countNonEmpty: function (refs) {
+      return resolve(refs).filter(function (el) { return textOf(el).length > 0; }).length;
+    },
+    text: function (refs) { return textOf(first(refs)); },
+    texts: function (refs) { return resolve(refs).map(textOf); },
+    visible: function (refs) { return isVisible(first(refs)); },
+    hidden: function (refs) { var els = resolve(refs); return !els.length || !isVisible(els[0]); },
+    exists: function (refs) { return resolve(refs).length > 0; },
+    attr: function (refs, name) { return attrOf(first(refs), name); },
+    classes: function (refs) { return classList(first(refs)); },
+    click: function (refs, dbl) { clickEl(first(refs), !!dbl); return "ok"; },
+    hover: function (refs) { var el = first(refs); el.scrollIntoView({ block: "center" }); mouse(el, "mouseover"); mouse(el, "mouseenter"); mouse(el, "mousemove"); return "ok"; },
+    type: function (refs, text) { setValue(first(refs), text); return "ok"; },
+    clear: function (refs) { setValue(first(refs), ""); return "ok"; },
+    scrollIntoView: function (refs) { first(refs).scrollIntoView({ block: "center", inline: "center" }); return "ok"; },
+    scrollPage: function (dy) { window.scrollBy(0, Number(dy) || 600); return "ok"; },
+    drag: function (srcRefs, dstRefs) { dragEl(first(srcRefs), first(dstRefs)); return "ok"; },
+    url: function () { return location.href; },
+    title: function () { return String(document.title || ""); },
+    waitSelector: function (css, visible) {
+      var els = locator().queryAllDeep(document, css);
+      if (!els.length) return false;
+      return visible === false ? !isVisible(els[0]) : isVisible(els[0]);
+    },
+    evaluate: function (expr) {
+      // 平台 WRITE_GLOBAL 的 javascript hop 是表达式形态
+      return (0, eval)("(" + expr + ")");
+    },
+  };
+  window.__keveOpsSource = "v1";
+  return "ok";
+})()`;
+}
+/**
+ * 网络记录：waitForResponse 的就绪门依赖它。
+ * 在 AUT 里最早注入，之后所有 fetch/XHR 都会留下 {url, method, status, at}。
+ * 只记录元数据不记录 body —— 读 body 会消费流，影响被测应用自身逻辑。
+ */
+function netLogSource() {
+    return `(() => {
+  "use strict";
+  if (window.__keveNetLogSource === "v1") return "cached";
+  var log = [];
+  window.__keveNetLog = log;
+
+  function push(entry) {
+    log.push(entry);
+    if (log.length > 500) log.splice(0, log.length - 500);
+  }
+
+  var origFetch = window.fetch;
+  if (typeof origFetch === "function") {
+    window.fetch = function (input, init) {
+      var url = typeof input === "string" ? input : (input && input.url) || "";
+      var method = String((init && init.method) || (input && input.method) || "GET").toUpperCase();
+      var at = Date.now();
+      var p = origFetch.apply(this, arguments);
+      if (p && typeof p.then === "function") {
+        p.then(function (res) {
+          push({ url: String(url), method: method, status: res && res.status, at: at });
+          return res;
+        }, function (err) {
+          push({ url: String(url), method: method, status: 0, at: at, error: String(err && err.message || err) });
+        });
+      }
+      return p;
+    };
+  }
+
+  var XO = XMLHttpRequest.prototype.open;
+  var XS = XMLHttpRequest.prototype.send;
+  XMLHttpRequest.prototype.open = function (method, url) {
+    this.__keve = { method: String(method || "GET").toUpperCase(), url: String(url || ""), at: Date.now() };
+    return XO.apply(this, arguments);
+  };
+  XMLHttpRequest.prototype.send = function () {
+    var self = this;
+    this.addEventListener("loadend", function () {
+      var meta = self.__keve || {};
+      push({ url: meta.url || "", method: meta.method || "GET", status: self.status, at: meta.at || Date.now() });
+    });
+    return XS.apply(this, arguments);
+  };
+
+  window.__keveNetLogSource = "v1";
+  return "ok";
+})()`;
+}
+/** 三项注入合并（幂等，重复调用无副作用） */
+function bootstrapSource(locatorSrc) {
+    return `${locatorSrc};\n${netLogSource()};\n${pageOpsSource()}`;
+}
+/**
+ * 运行诊断采集（AUT 主世界）。
+ *
+ * Cypress 侧不能订阅 CDP 域事件（`Cypress.automation` 只有 request/response，
+ * 没有 domain event 通道），所以这里在**主世界**劫持 console / 全局错误 /
+ * fetch / XHR，并用 PerformanceObserver 采集 LCP 与 longtask。
+ *
+ * 采集结果写入 `document.documentElement.dataset.keveDiagnostics`，因为
+ * isolated world 与主世界共享 DOM、但不共享 JS 全局，DOM 属性是唯一稳定的
+ * 跨世界只读通道。Agent 结束后由 isolated world 读一次快照即可。
+ *
+ * 约束：
+ *   - 必须调用原始 console / fetch / XHR，避免递归采集；
+ *   - 不读 body（会消费流，影响被测应用）；
+ *   - 文本与样本都做截断/限量，避免诊断本身撑爆报告；
+ *   - 只写 DOM 属性，不改 `window.__keveNetLog`（waitForResponse 依赖它）。
+ */
+function diagnosticsSource() {
+    return `(() => {
+  "use strict";
+  if (window.__keveDiagnosticsSource === "v1") return "cached";
+
+  var MAX_TEXT = 1000;
+  var MAX_RECORDS = 300;
+  var browserRecords = [];
+  var networkRecords = [];
+  var flushTimer = null;
+  var lcpMs = 0;
+  var longTaskCount = 0;
+  var longTaskMs = 0;
+
+  function clip(value, max) {
+    var s = String(value == null ? "" : value);
+    return s.length > max ? s.slice(0, max) + "…" : s;
+  }
+
+  function flush() {
+    try {
+      var root = document.documentElement || document.body;
+      if (!root) {
+        scheduleFlush();
+        return;
+      }
+      var page = {};
+      try {
+        var nav = (performance.getEntriesByType && performance.getEntriesByType("navigation") || [])[0];
+        if (nav) {
+          if (nav.domContentLoadedEventEnd) page.domContentLoadedMs = Math.round(nav.domContentLoadedEventEnd);
+          if (nav.loadEventEnd) page.loadMs = Math.round(nav.loadEventEnd);
+        }
+        if (lcpMs > 0) page.lcpMs = Math.round(lcpMs);
+        if (longTaskCount > 0) {
+          page.longTaskCount = longTaskCount;
+          page.longTaskMs = Math.round(longTaskMs);
+        }
+        var mem = performance.memory;
+        if (mem && mem.usedJSHeapSize) page.heapUsedMb = Math.round(mem.usedJSHeapSize / 1048576 * 10) / 10;
+      } catch (e) { /* 性能 API 缺失时忽略 */ }
+      root.dataset.keveDiagnostics = JSON.stringify({
+        browser: browserRecords,
+        network: networkRecords,
+        page: page
+      });
+    } catch (e) { /* 属性写入失败不影响用例 */ }
+  }
+
+  function scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(function () {
+      flushTimer = null;
+      flush();
+    }, 100);
+  }
+
+  function pushBrowser(kind, level, text) {
+    browserRecords.push({ kind: kind, level: level, text: clip(text, MAX_TEXT), at: Date.now() });
+    if (browserRecords.length > MAX_RECORDS) browserRecords.splice(0, browserRecords.length - MAX_RECORDS);
+    scheduleFlush();
+  }
+
+  function pushNetwork(entry) {
+    entry.url = clip(entry.url, 500);
+    if (entry.error) entry.error = clip(entry.error, 300);
+    networkRecords.push(entry);
+    if (networkRecords.length > MAX_RECORDS) networkRecords.splice(0, networkRecords.length - MAX_RECORDS);
+    scheduleFlush();
+  }
+
+  // ── Console：只摘 error/warn，普通 log 不占样本额度 ──
+  ["error", "warn"].forEach(function (level) {
+    var orig = console[level];
+    if (typeof orig !== "function") return;
+    console[level] = function () {
+      try {
+        pushBrowser("console", level, Array.prototype.map.call(arguments, function (a) {
+          if (a instanceof Error) return a.stack || a.message;
+          if (typeof a === "object") {
+            try { return JSON.stringify(a); } catch (e) { return String(a); }
+          }
+          return String(a);
+        }).join(" "));
+      } catch (e) { /* 采集失败不影响原始输出 */ }
+      return orig.apply(console, arguments);
+    };
+  });
+
+  // ── 全局未捕获错误 / 未处理的 Promise rejection ──
+  window.addEventListener("error", function (event) {
+    var err = event && event.error;
+    var text = (err && (err.stack || err.message)) || (event && event.message) || "unknown error";
+    pushBrowser("pageerror", "error", text);
+  }, true);
+
+  window.addEventListener("unhandledrejection", function (event) {
+    var reason = event && event.reason;
+    var text = (reason && (reason.stack || reason.message)) || String(reason || "unhandled rejection");
+    pushBrowser("exception", "error", text);
+  });
+
+  // ── fetch ──
+  var origFetch = window.fetch;
+  if (typeof origFetch === "function") {
+    window.fetch = function (input, init) {
+      var url = typeof input === "string" ? input : (input && input.url) || "";
+      var method = String((init && init.method) || (input && input.method) || "GET").toUpperCase();
+      var startedAt = Date.now();
+      var p = origFetch.apply(this, arguments);
+      if (p && typeof p.then === "function") {
+        p.then(function (res) {
+          pushNetwork({
+            url: String(url),
+            method: method,
+            status: res && res.status,
+            durationMs: Date.now() - startedAt,
+            at: startedAt
+          });
+          return res;
+        }, function (err) {
+          pushNetwork({
+            url: String(url),
+            method: method,
+            status: 0,
+            durationMs: Date.now() - startedAt,
+            error: String((err && err.message) || err),
+            at: startedAt
+          });
+        });
+      }
+      return p;
+    };
+  }
+
+  // ── XHR ──
+  var XO = XMLHttpRequest.prototype.open;
+  var XS = XMLHttpRequest.prototype.send;
+  XMLHttpRequest.prototype.open = function (method, url) {
+    this.__keveDiag = {
+      method: String(method || "GET").toUpperCase(),
+      url: String(url || ""),
+      startedAt: Date.now()
+    };
+    return XO.apply(this, arguments);
+  };
+  XMLHttpRequest.prototype.send = function () {
+    var self = this;
+    this.addEventListener("loadend", function () {
+      var meta = self.__keveDiag || {};
+      pushNetwork({
+        url: meta.url || "",
+        method: meta.method || "GET",
+        status: self.status,
+        durationMs: meta.startedAt ? Date.now() - meta.startedAt : undefined,
+        error: self.status === 0 ? "network error" : undefined,
+        at: meta.startedAt
+      });
+    });
+    return XS.apply(this, arguments);
+  };
+
+  // ── 性能：LCP / longtask（buffered 让先发生的条目也能补收） ──
+  try {
+    if (typeof PerformanceObserver === "function") {
+      var lcpObs = new PerformanceObserver(function (list) {
+        var entries = list.getEntries();
+        for (var i = 0; i < entries.length; i++) {
+          var t = entries[i].startTime || entries[i].renderTime || 0;
+          if (t > lcpMs) lcpMs = t;
+        }
+        scheduleFlush();
+      });
+      lcpObs.observe({ type: "largest-contentful-paint", buffered: true });
+
+      var longObs = new PerformanceObserver(function (list) {
+        var entries = list.getEntries();
+        for (var j = 0; j < entries.length; j++) {
+          longTaskCount += 1;
+          longTaskMs += Number(entries[j].duration || 0);
+        }
+        scheduleFlush();
+      });
+      longObs.observe({ type: "longtask", buffered: true });
+    }
+  } catch (e) { /* 浏览器不支持时静默降级 */ }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", flush, { once: true });
+  }
+  window.addEventListener("load", flush, { once: true });
+  // isolated world 读取前会 dispatch 该事件，要求主世界立即刷新 DOM 快照，
+  // 避免最后一条网络/console 记录落在 debounce 窗口里没被读走。
+  window.addEventListener("keve:flush-diagnostics", flush);
+
+  window.__keveDiagnosticsSource = "v1";
+  flush();
+  return "ok";
+})()`;
+}

package/dist/engine-cypress/reporter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * reporter — Cypress 侧结果收集
+ *
+ * Cypress 没有 Playwright 那种「进程内 Reporter」能直接拿到 TestCase/TestResult；
+ * 这里用全局 afterEach 捞出当前用例的状态，经 HTTP 桥送回 Node 落盘。
+ *
+ * 落盘形态与 Playwright 完全一致：
+ *   - confidence-data.jsonl：由 core/confidence.ts 的分类逻辑生成（同源）
+ *   - test-results.json：Playwright JSON reporter 的结构（bridge 内合成）
+ *   - report-data.json：同一份 generateReportData 汇总
+ *
+ * Mocha 的 afterEach 拿不到「用例耗时」的精确起点，这里用 beginTestState 的
+ * 时间戳兜底；Cypress 的 `this.currentTest.duration` 在有值时优先。
+ */
+/**
+ * 安装结果收集钩子。
+ * 需要在场景注册之前调用（与 installCypressHost 同一时机），保证 afterEach
+ * 能拿到装饰器执行过程中写入 state 的附件。
+ */
+export declare function installCypressReporter(): void;

package/dist/engine-cypress/reporter.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * reporter — Cypress 侧结果收集
+ *
+ * Cypress 没有 Playwright 那种「进程内 Reporter」能直接拿到 TestCase/TestResult；
+ * 这里用全局 afterEach 捞出当前用例的状态，经 HTTP 桥送回 Node 落盘。
+ *
+ * 落盘形态与 Playwright 完全一致：
+ *   - confidence-data.jsonl：由 core/confidence.ts 的分类逻辑生成（同源）
+ *   - test-results.json：Playwright JSON reporter 的结构（bridge 内合成）
+ *   - report-data.json：同一份 generateReportData 汇总
+ *
+ * Mocha 的 afterEach 拿不到「用例耗时」的精确起点，这里用 beginTestState 的
+ * 时间戳兜底；Cypress 的 `this.currentTest.duration` 在有值时优先。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installCypressReporter = installCypressReporter;
+const adapter_js_1 = require("./adapter.js");
+const state_js_1 = require("./state.js");
+/** 从 Mocha 的 currentTest 里取错误文案（Cypress 会把失败信息挂在不同字段） */
+function extractError(test) {
+    if (!test)
+        return undefined;
+    const err = test.err;
+    if (!err)
+        return undefined;
+    return String(err.message || err.stack || err);
+}
+function mapStatus(test) {
+    const state = String(test?.state || '');
+    if (state === 'passed')
+        return 'passed';
+    if (state === 'pending')
+        return 'skipped';
+    if (test?.timedOut)
+        return 'timedOut';
+    return 'failed';
+}
+/**
+ * suite 标题 = @keveModel 注册时的 describe 标题（`M_SG90061: …`）。
+ *
+ * Cypress 12 的 Mocha Test 上**没有** `titlePath`（探针实测 ownKeys 无此字段），
+ * 只能沿 `parent` 链向上收集，取最靠近用例的那个非 root 祖先标题 —— 语义等价于
+ * Playwright `suitePath` 的末段，reportData.buildCaseResultMap 就是按末段取模块名。
+ */
+function suiteTitleOf(test) {
+    const titles = [];
+    let node = test?.parent;
+    while (node && !node.root) {
+        if (node.title)
+            titles.push(String(node.title));
+        node = node.parent;
+    }
+    return titles.length ? titles[titles.length - 1] : '';
+}
+let installed = false;
+/**
+ * 安装结果收集钩子。
+ * 需要在场景注册之前调用（与 installCypressHost 同一时机），保证 afterEach
+ * 能拿到装饰器执行过程中写入 state 的附件。
+ */
+function installCypressReporter() {
+    if (installed)
+        return;
+    installed = true;
+    const c = globalThis.Cypress;
+    const afterEach = c?.afterEach || globalThis.afterEach;
+    if (typeof afterEach !== 'function') {
+        throw new Error('[cypress-engine] 未找到 afterEach：本模块只能在 Cypress spec 中运行');
+    }
+    // 注册在根级：Cypress 会先跑 suite 内的 afterEach（场景 afterHook），最后跑根级；
+    // 因此这里能拿到装饰器执行期间写入的全部附件。
+    afterEach(function () {
+        const test = this.currentTest;
+        if (!test)
+            return;
+        const state = (0, state_js_1.getTestState)();
+        const suiteTitle = suiteTitleOf(test);
+        const title = state?.title || '';
+        // 只认 @keveScene 注册的用例：state 必须存在且标题形如 `S90061: 描述`。
+        // 注意不能退化成看 suite 标题前缀 —— Cypress 在 hook 失败时也会跑根级 afterEach，
+        // 那时 suite 名仍是 `M_` 开头，会把 hook 误收成一条空用例（state.title 为空）。
+        if (!state || !/^[A-Z][A-Z0-9_]*\d*:/.test(title))
+            return;
+        const rawStatus = mapStatus(test);
+        // 应用侧未捕获异常已被 Cypress 放行（return false），不会中断测试执行；
+        // 最终状态仍以 Cypress 的真实用例结果为准。通过用例不因页面运行时噪音
+        // 显示失败，失败用例再把未捕获异常合并进错误文本做根因补充。
+        const uncaughtErrors = state?.uncaughtErrors || [];
+        const status = rawStatus;
+        const testError = rawStatus === 'passed' || rawStatus === 'skipped' ? undefined : extractError(test);
+        const error = uncaughtErrors.length && rawStatus !== 'passed' && rawStatus !== 'skipped'
+            ? [...uncaughtErrors, testError || ''].filter(Boolean).join('\n')
+            : testError;
+        const record = {
+            title,
+            suiteTitle,
+            file: state?.file || '',
+            status,
+            duration: Number(test.duration || 0),
+            startTime: new Date(Date.now() - Number(test.duration || 0)).toISOString(),
+            error,
+            logs: state?.logs || [],
+            uncaughtErrors,
+            attachments: state?.attachments || [],
+        };
+        (0, state_js_1.endTestState)();
+        // 必须 return Cypress 链：这样 Cypress 会等请求真正返回后才结束该 hook，
+        // 保证 after:run（Node 侧 finalize）读到的是完整结果集。
+        // 注意不能用 `await cy.xxx()`，只能用返回链的形态。
+        // 注意：这里必须是命令链 `cy.wrap`，不是运行时对象 `Cypress.wrap`（不存在）。
+        const chain = globalThis.cy;
+        if (!chain || typeof chain.wrap !== 'function') {
+            console.error(`[cypress-engine] 结果落盘失败（${record.title}）：未找到 cy 命令链`);
+            return;
+        }
+        return chain.wrap(null, { log: false }).then({ timeout: 60_000 }, async () => {
+            try {
+                const out = await (0, adapter_js_1.createBridge)().post('/report/test', record);
+                if (!out?.ok)
+                    throw new Error(out?.error || 'unknown');
+            }
+            catch (err) {
+                console.error(`[cypress-engine] 结果落盘失败（${record.title}）：${err?.message || err}`);
+            }
+        });
+    });
+}

package/dist/engine-cypress/setup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @kkeve/suite/engine-cypress/setup — Cypress 引擎的 Node 侧入口
+ *
+ * 只给 cypress.config 的 `setupNodeEvents` 使用（Node 环境）：
+ *
+ *   import { cypressSetup } from '@kkeve/suite/engine-cypress/setup';
+ *
+ *   export default defineConfig({
+ *     e2e: {
+ *       setupNodeEvents(on, config) {
+ *         return cypressSetup(on, config);
+ *       },
+ *     },
+ *   });
+ *
+ * 职责：起本地 HTTP 桥（截图对比 / 文件落盘 / 报告汇总），并把端口写回 config.env。
+ * ⚠️ 绝不能从浏览器侧入口（@kkeve/suite/engine-cypress）import 本模块 ——
+ * 它依赖 node:http / node:fs。
+ */
+export { setupKeveBridge, setupKeveBridge as cypressSetup, type CypressTestResultRecord, } from './bridge.js';
+export { setupKeveBridge as default } from './bridge.js';

package/dist/engine-cypress/setup.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * @kkeve/suite/engine-cypress/setup — Cypress 引擎的 Node 侧入口
+ *
+ * 只给 cypress.config 的 `setupNodeEvents` 使用（Node 环境）：
+ *
+ *   import { cypressSetup } from '@kkeve/suite/engine-cypress/setup';
+ *
+ *   export default defineConfig({
+ *     e2e: {
+ *       setupNodeEvents(on, config) {
+ *         return cypressSetup(on, config);
+ *       },
+ *     },
+ *   });
+ *
+ * 职责：起本地 HTTP 桥（截图对比 / 文件落盘 / 报告汇总），并把端口写回 config.env。
+ * ⚠️ 绝不能从浏览器侧入口（@kkeve/suite/engine-cypress）import 本模块 ——
+ * 它依赖 node:http / node:fs。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.cypressSetup = exports.setupKeveBridge = void 0;
+var bridge_js_1 = require("./bridge.js");
+Object.defineProperty(exports, "setupKeveBridge", { enumerable: true, get: function () { return bridge_js_1.setupKeveBridge; } });
+Object.defineProperty(exports, "cypressSetup", { enumerable: true, get: function () { return bridge_js_1.setupKeveBridge; } });
+var bridge_js_2 = require("./bridge.js");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return bridge_js_2.setupKeveBridge; } });

package/dist/engine-cypress/shotBuffer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * shotBuffer — 截图对比结果的 goal 级缓冲（浏览器侧）
+ *
+ * core/screenshotDiff.ts 是 Node 模块（依赖 fs），不能被打进 Cypress 的浏览器
+ * bundle。但结构必须一致：keveGoal 要把本 goal 内所有对比结果（matched /
+ * baseline_required / exceeded）写进 attachment 的 screenshotDiff 字段。
+ * 这里只做「暂存 + 取出」，真正的对比在 Node 侧经 bridge 完成。
+ */
+export interface CyShotDiffResult {
+    key: string;
+    status: 'matched' | 'exceeded' | 'baseline_required' | 'size_mismatch';
+    diffRatio: number | null;
+    threshold: number;
+    baselineVersion: number;
+    baselineState?: 'candidate' | 'active';
+    baselinePath: string;
+    actualPath: string;
+    diffPath: string;
+    env: string;
+    viewport: string;
+    /** 差异热区（与 core/screenshotDiff.ts 的 ShotDiffResult.regions 同形，始终存在） */
+    regions: Array<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        ratio: number;
+    }>;
+    message: string;
+    comparedAt: string;
+}
+/** 与 Playwright 的 ScreenshotDiffError 同形：带 shotDiff 结构，keveGoal 据此短路 */
+export declare class CypressScreenshotDiffError extends Error {
+    shotDiff: CyShotDiffResult;
+    constructor(result: CyShotDiffResult);
+}
+export declare function beginGoalShotDiffCapture(): void;
+export declare function isGoalShotDiffCaptureActive(): boolean;
+export declare function drainGoalShotDiff(): CyShotDiffResult[];
+export declare function recordShotDiff(result: CyShotDiffResult): void;