@kkeve/suite 0.0.15 → 0.0.17

package/dist/engine-cypress/keveGoal.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * keveGoal — Cypress 版的唯一操作原语
+ *
+ * 与 Playwright 的 keveGoal fixture（core/keve-test.ts）**语义同构**：
+ *   - 记录 goal 元数据到 sceneGoalsMap（报告归因用）
+ *   - fn 前 / fn 后各截一张图，落盘后写进 attachment
+ *   - fn 成功/失败都进入 Agent Re-Act，由观察真实页面后给最终结论；
+ *     仅截图差异超阈值、环境阻断这两类确定性事实短路
+ *   - 产物是 `keveGoalResult` attachment，字段与 Playwright 完全一致
+ *
+ * 唯一的实现差异：截图与落盘必须经 HTTP 桥（cy.task 在 async cy.then 内不可 await）。
+ * 所以这里不 import 任何 Node 模块，也不 import @playwright/test。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCyGoalExplorer = setCyGoalExplorer;
+exports.createCyKeveGoal = createCyKeveGoal;
+const keve_registry_js_1 = require("../core/decorator/keve-registry.js");
+const keve_aspect_js_1 = require("../core/decorator/keve-aspect.js");
+const goal_heuristics_js_1 = require("../core/judge/goal-heuristics.js");
+const shotBuffer_js_1 = require("./shotBuffer.js");
+const state_js_1 = require("./state.js");
+/** 由引擎入口注册的探索器（P0-3：Cypress 侧 AI Re-Act） */
+let explorer = null;
+function setCyGoalExplorer(fn) {
+    explorer = fn;
+}
+/** 与 Playwright captureScreenshot 的 safeName 规则保持一致，保证两端截图文件名同形。 */
+function safeStepName(step) {
+    return String(step || 'step').replace(/[^a-zA-Z0-9一-鿿]/g, '_').slice(0, 30);
+}
+/**
+ * 同时输出到 Cypress 控制台与用例日志缓冲。
+ *
+ * spec 内的 console.log 只留在浏览器控制台，不会进 Node 进程输出，因此
+ * Playwright 报告中那条 `[keveGoal]` stdout 轨迹在 Cypress 下会整段缺失。
+ * 这里双写，让 stdout 字段两端同构。
+ */
+function logLine(line) {
+    console.log(line);
+    (0, state_js_1.addLog)(line);
+}
+function createCyKeveGoal(engine) {
+    return async (options, fn) => {
+        const state = (0, state_js_1.requireTestState)();
+        const order = (0, state_js_1.nextGoalOrder)();
+        const goalMeta = {
+            precondition: options.precondition,
+            step: options.step,
+            expected: options.expected,
+            order,
+        };
+        if (!keve_registry_js_1.sceneGoalsMap.has(state.title))
+            keve_registry_js_1.sceneGoalsMap.set(state.title, []);
+        keve_registry_js_1.sceneGoalsMap.get(state.title).push(goalMeta);
+        const ctx = {
+            // Cypress 下没有 Playwright Page；探索层用 engine.rawPage() 拿 CDP 驱动
+            page: engine.rawPage(),
+            engine,
+            step: options.step,
+            expected: options.expected,
+            precondition: options.precondition,
+            order,
+            testTitle: state.title,
+            specFilePath: state.file,
+        };
+        await keve_aspect_js_1.keveAspect.runPhase('before', ctx);
+        // ── goal-before 截图（动作发生前的页面原始状态） ──
+        let goalScreenshotBefore = '';
+        try {
+            goalScreenshotBefore = await engine.captureArtifact(`goal-before-${order}-${safeStepName(options.step)}`);
+        }
+        catch { /* 截图非关键路径 */ }
+        let fnError;
+        let fnErrorRaw;
+        let fnResult;
+        let fnBlocked = false;
+        const fnSource = fn?.toString() || undefined;
+        const owned = !(0, shotBuffer_js_1.isGoalShotDiffCaptureActive)();
+        if (owned)
+            (0, shotBuffer_js_1.beginGoalShotDiffCapture)();
+        if (fn) {
+            try {
+                fnResult = await fn();
+                logLine(`[keveGoal] "${options.step}" fn executed`);
+            }
+            catch (err) {
+                fnError = err?.message || String(err);
+                fnErrorRaw = err;
+                fnBlocked = (0, goal_heuristics_js_1.isEnvironmentBlockedError)(err);
+                logLine(`[keveGoal] "${options.step}" fn error: ${fnError}`);
+                // 页面级权限阻断：fn 报的是定位失败，根因是访问被拒 → 按 blocked 归因
+                if (!fnBlocked && fnError) {
+                    try {
+                        const blockedUrl = await engine.currentUrl();
+                        if (/\/forbidden|\/unauthorized|\/403|\/no-permission/i.test(blockedUrl)) {
+                            fnBlocked = true;
+                            fnError = `页面访问被阻断（当前 URL=${blockedUrl}），目标元素未渲染 — 权限或数据问题，非用例缺陷`;
+                        }
+                    }
+                    catch { /* URL 读不到则保持原错误 */ }
+                }
+            }
+        }
+        const shotDiffs = owned ? (0, shotBuffer_js_1.drainGoalShotDiff)() : [];
+        // ── fn-after 截图（执行后的页面状态） ──
+        let fnAfterScreenshot = '';
+        if (fn) {
+            try {
+                fnAfterScreenshot = await engine.captureArtifact(`goal-after-fn-${order}-${safeStepName(options.step)}`);
+            }
+            catch { /* 非关键 */ }
+        }
+        // ── 判定 ──
+        let reactResult;
+        if (fnBlocked) {
+            reactResult = {
+                expectedMet: false,
+                conclusion: 'blocked',
+                actions: [{
+                        action: { tool: 'done', verdict: 'blocked', text: `Environment blocked: ${fnError}` },
+                        toolOutput: '',
+                        result: 'ok',
+                    }],
+                agentScreenshots: [],
+            };
+            console.log(`[keveGoal] 🚫 "${options.step}" BLOCKED — 环境错误，跳过 Agent Re-Act`);
+        }
+        else if (fnErrorRaw?.name === 'ScreenshotDiffError') {
+            reactResult = {
+                expectedMet: false,
+                conclusion: 'fail',
+                actions: [{
+                        action: { tool: 'done', verdict: 'fail', text: fnError },
+                        toolOutput: fnErrorRaw.shotDiff?.message || '',
+                        result: 'ok',
+                    }],
+                agentScreenshots: [],
+            };
+            console.log(`[keveGoal] 📊 "${options.step}" 截图差异超阈值 — 确定性失败`);
+        }
+        else {
+            // fn 成功 / 失败都交给探索器（若引擎入口注册了 AI Re-Act）。
+            // fn 只是前置确定性校验，@keveGoal 的预期是否真正达成必须由 Agent
+            // 观察真实页面后给出最终结论 —— 即便 fn 已通过，也要产出推理轨迹与
+            // 执行后截图，否则报告里会缺少 AI 推理日志。
+            let explored;
+            if (explorer) {
+                try {
+                    logLine(fnError
+                        ? `[keveGoal] 🤖 "${options.step}" fn failed — entering Agent Re-Act`
+                        : `[keveGoal] 🤖 "${options.step}" fn succeeded — entering Agent Re-Act for final verdict`);
+                    explored = await explorer(options, {
+                        fnSource,
+                        fnError,
+                        goalScreenshotBefore: goalScreenshotBefore || undefined,
+                        fnAfterScreenshot: fnAfterScreenshot || undefined,
+                        specFilePath: state.file || undefined,
+                        testTitle: state.title,
+                    });
+                }
+                catch (err) {
+                    // Cypress 下浏览器控制台不回流 Node stdout，必须同时写用例日志，否则
+                    // 探索层异常在 CI 里完全不可见（报告只剩一个没有归因的 fail）。
+                    logLine(`[keveGoal] ⚠️ "${options.step}" 探索异常：${err?.message || err}`);
+                }
+            }
+            else {
+                logLine(`[keveGoal] ℹ️ "${options.step}" 未注册探索器，跳过 Agent Re-Act`);
+            }
+            reactResult = explored || {
+                expectedMet: false,
+                conclusion: (0, goal_heuristics_js_1.isAssertionFailure)(fnError) ? 'fail' : 'fail',
+                actions: [{
+                        action: { tool: 'done', verdict: 'fail', text: fnError },
+                        toolOutput: '',
+                        result: 'ok',
+                    }],
+                agentScreenshots: [],
+            };
+        }
+        // ── 确定性覆盖：fn 断言失败不允许被 Agent 判成 pass ──
+        if (fnError && !fnBlocked && reactResult.expectedMet && (0, goal_heuristics_js_1.isAssertionFailure)(fnError)) {
+            console.log(`[keveGoal] ⚠️ "${options.step}" Agent 判 PASS 但 fn 断言失败 — 覆盖为 FAIL`);
+            reactResult.expectedMet = false;
+            reactResult.conclusion = 'fail';
+        }
+        const conclusion = reactResult.expectedMet ? 'pass' : (reactResult.conclusion || 'fail');
+        const success = reactResult.expectedMet;
+        const errorMessage = success
+            ? undefined
+            : conclusion === 'blocked'
+                ? `Blocked: ${fnBlocked ? fnError : (reactResult.actions || []).filter((a) => a.action?.tool === 'done').pop()?.action?.text || 'Agent blocked'}`
+                : fnErrorRaw?.name === 'ScreenshotDiffError'
+                    ? fnError
+                    : fnError && (0, goal_heuristics_js_1.isAssertionFailure)(fnError)
+                        ? `Assertion failed: ${fnError}`
+                        : `Expected not achieved: ${options.expected}`;
+        // 与 Playwright keve-test.ts 的终局日志同形，保证两端执行轨迹可逐行对照
+        logLine(success
+            ? `[keveGoal] ✅ "${options.step}" PASSED`
+            : `[keveGoal] ❌ "${options.step}" FAILED (${conclusion}) — ${errorMessage}`);
+        // ── goal-after：优先取 agent done 时刻的截图，否则用 fn-after ──
+        let goalScreenshotAfter = '';
+        try {
+            const lastWithShot = [...(reactResult.actions || [])].reverse().find((a) => a.screenshotPath);
+            if (lastWithShot?.screenshotPath)
+                goalScreenshotAfter = String(lastWithShot.screenshotPath);
+        }
+        catch { /* 非关键 */ }
+        const goalResultPayload = {
+            step: options.step,
+            expected: options.expected,
+            precondition: options.precondition,
+            order,
+            success,
+            actions: (reactResult.actions || []).map((a) => ({
+                tool: a.action?.tool,
+                role: a.action?.role,
+                name: a.action?.name,
+                url: a.action?.url,
+                text: a.action?.text,
+                toolOutput: typeof a.toolOutput === 'string' ? a.toolOutput.slice(0, 500) : undefined,
+                reason: a.action?.reason,
+                success: a.action?.success,
+                verdict: a.action?.verdict,
+                conclusion: (0, goal_heuristics_js_1.deriveActionConclusion)(reactResult.conclusion, a.action),
+                result: a.result,
+                error: a.error,
+                evaluation: typeof a.evaluation === 'string' ? a.evaluation.slice(0, 300) : undefined,
+                memory: typeof a.memory === 'string' ? a.memory.slice(0, 200) : undefined,
+                nextGoal: typeof a.nextGoal === 'string' ? a.nextGoal.slice(0, 200) : undefined,
+                screenshotPath: a.screenshotPath,
+            })),
+            finalSnapshot: reactResult.finalSnapshot ? String(reactResult.finalSnapshot).slice(0, 500) : undefined,
+            diagnosticHints: reactResult.diagnosticHints || [],
+            diagnostics: reactResult.diagnostics,
+            goalScreenshotBefore: goalScreenshotBefore || undefined,
+            goalScreenshotAfter: goalScreenshotAfter || undefined,
+            // 注意不能写成 `|| [...]`：空数组是 truthy，会把 fn-after 兜底截图短路丢弃。
+            agentScreenshots: reactResult.agentScreenshots?.length
+                ? reactResult.agentScreenshots
+                : (fnAfterScreenshot ? [fnAfterScreenshot] : []),
+            screenshotDiff: shotDiffs.length ? shotDiffs : undefined,
+            conclusion,
+        };
+        (0, state_js_1.addAttachment)({
+            name: 'keveGoalResult',
+            contentType: 'application/json',
+            // base64 编码：与 Playwright JSON reporter 的 attachment body 序列化格式一致
+            body: (0, state_js_1.encodeAttachmentBody)(JSON.stringify(goalResultPayload)),
+        });
+        const result = {
+            success,
+            conclusion,
+            actions: reactResult.actions || [],
+            finalSnapshot: reactResult.finalSnapshot,
+            error: success ? undefined : new Error(errorMessage),
+        };
+        await keve_aspect_js_1.keveAspect.runPhase('after', ctx, result, result.error);
+        if (!success)
+            throw result.error || new Error(`keveGoal "${options.step}" failed`);
+        return fnResult;
+    };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * pageOps — 注入 AUT 的「操作原语 + 网络记录」源码
+ *
+ * 与 locatorSource.ts 同样以「自包含源码字符串」形式注入：isolated world 里的
+ * 函数无法闭包引用 bundle 变量，只能整段送过去求值。
+ *
+ * 职责边界：
+ *   locatorSource → 定位（ElementRef / hop 链 → 元素集合）
+ *   pageOps       → 动作与读取（点击/输入/拖拽/文本/可见性/属性/滚动）
+ *   netLog        → fetch/XHR 记录，支撑 waitForResponse 的软等待门
+ *
+ * 交互走原生 DOM 事件（探针已验证 React 合成事件能正常响应），
+ * 与 Playwright 的 locator click 在「触发应用逻辑」这一层语义等价。
+ */
+export declare function pageOpsSource(): string;
+/**
+ * 网络记录：waitForResponse 的就绪门依赖它。
+ * 在 AUT 里最早注入，之后所有 fetch/XHR 都会留下 {url, method, status, at}。
+ * 只记录元数据不记录 body —— 读 body 会消费流，影响被测应用自身逻辑。
+ */
+export declare function netLogSource(): string;
+/** 三项注入合并（幂等，重复调用无副作用） */
+export declare function bootstrapSource(locatorSrc: string): string;
+/**
+ * 运行诊断采集（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 依赖它）。
+ */
+export declare function diagnosticsSource(): string;