@szc-ft/mcp-szcd-client 0.27.4 → 0.28.0

package/lib/browser-engine.js

@@ -12,6 +12,8 @@
  */
 
 import { findChrome, getChromeInstallGuide } from "./chrome-finder.js";
+import { AntAdapter } from "./ant-adapter.js";
+import { createExpect, locator as expectLocator, validation as expectValidation, url as expectUrl, api as expectApi } from "./expect.js";
 
 export class BrowserEngine {
     constructor() {
@@ -20,6 +22,20 @@ export class BrowserEngine {
         this.mode = null;        // 'connect' | 'launch'
         this.ownedBrowser = false; // launch 模式为 true，决定关闭时是否 kill
         this._activeFrame = null;  // 当前活跃 iframe 上下文（微前端场景）
+        this._adapter = null;      // 懒加载 AntAdapter
+        this._lastActWasDropdown = false; // 用于 act 入口自动 closeAllDropdowns
+    }
+
+    /**
+     * 获取 / 懒初始化 AntAdapter，支持 componentMeta 注入（来自 szcd MCP 私有组件元数据）
+     */
+    _getAdapter(componentMeta) {
+        if (!this._adapter) {
+            this._adapter = new AntAdapter({ componentMeta: componentMeta || {} });
+        } else if (componentMeta) {
+            this._adapter.componentMeta = { ...this._adapter.componentMeta, ...componentMeta };
+        }
+        return this._adapter;
     }
 
     /**
@@ -147,6 +163,7 @@ export class BrowserEngine {
             const result = await this._dispatchStep(step, context);
             if (step.type === "apiCapture" || step.type === "api-capture") {
                 context.lastApiCapture = result;
+                this._lastApiCapture = result; // 同步到 engine，供 _expect 使用
             }
             return {
                 ...result,
@@ -217,6 +234,17 @@ export class BrowserEngine {
     }
 
     async act(options = {}) {
+        // 上一次操作是 antSelect/antTreeSelect 等下拉控件 → 先关闭残留浮层（反馈第 3 条）
+        // 跨 frame 清理：覆盖主 frame + 子应用 iframe（微前端场景）
+        if (this._lastActWasDropdown && !options.skipCloseDropdowns) {
+            try {
+                await this._closeDropdownsAllFrames(this._activeFrame || this.page.mainFrame());
+                this._lastActWasDropdown = false;
+            } catch {
+                // closeAllDropdowns 失败不影响 act 继续
+            }
+        }
+
         const targetFrame = await this._resolveObserveFrame(options);
         if (options.menuPath) {
             return this._actMenuPath(targetFrame, options);
@@ -687,12 +715,15 @@ export class BrowserEngine {
             session.on("Network.requestWillBeSent", (event) => {
                 const request = event.request || {};
                 if (!matchesUrl(request.url) || !matchesMethod(request.method)) return;
+                // 为每条请求记录 frameUrl：关键的是框架帧的 URL，不是发起者 iframe 的 document
+                // event.frameId / event.loaderId 可关联到 Page.frameNavigated 事件
                 requests.set(`${targetInfo.id}:${event.requestId}`, {
                     id: event.requestId,
                     targetId: targetInfo.id,
                     targetType: targetInfo.type,
                     targetUrl: targetInfo.url,
                     frameId: event.frameId,
+                    frameUrl: targetInfo.url,  // 请求来源的 frame URL
                     url: request.url,
                     method: request.method,
                     requestHeaders: normalizeHeaders(request.headers),
@@ -1126,11 +1157,309 @@ export class BrowserEngine {
             case "aiAssert":     return this._aiAssert(step, context);
             case "runTask":      return this.runTask(step, context);
             case "run-task":     return this.runTask(step, context);
+            // ===== Ant Design 适配层（6/22 反馈落地） =====
+            case "antSelect":    return this._antSelect(step);
+            case "antTreeSelect":return this._antTreeSelect(step);
+            case "antInput":     return this._antInput(step);
+            case "antRadio":     return this._antRadio(step);
+            case "antCheckbox":  return this._antCheckbox(step);
+            case "antSwitch":    return this._antSwitch(step);
+            case "antDatePicker":return this._antDatePicker(step);
+            case "antCascader":  return this._antCascader(step);
+            case "antUpload":    return this._antUpload(step);
+            case "formFill":     return this._formFill(step);
+            case "closeAllDropdowns": return this._closeAllDropdowns(step);
+            // ===== 语义断言层 =====
+            case "expect":       return this._expect(step);
             default:
                 throw new Error(`Unknown step type: ${step.type}`);
         }
     }
 
+    /**
+     * 解析目标 frame，优先级（微前端场景兼容）：
+     *   1. step 显式传 frameContentContains / frameUrlContains / frameIndex → 用 _resolveObserveFrame
+     *   2. 已有 _activeFrame（来自 setup.findFrame / 上一步 findFrame）→ 直接复用
+     *   3. 否则回退到 mainFrame
+     *
+     * 同时做"frame 探活 + 自动召回"：如果 _activeFrame 因子应用卸载而失效，
+     * 自动清空并回退到 mainFrame，避免无限挂在已销毁的 frame 上。
+     *
+     * @returns {Promise<{frame, frameId, matchedBy, frameRecovered?}>} 含 frameRecovered 标志
+     */
+    async _getTargetFrame(step) {
+        const hasExplicitFrame = step && (step.frameContentContains || step.frameUrlContains || step.frameIndex !== undefined);
+
+        // 路径 1：显式指定 frame → 总是用 _resolveObserveFrame
+        if (hasExplicitFrame) {
+            const resolved = await this._resolveObserveFrame(step);
+            return { frame: resolved.frame, frameId: resolved.frameId, matchedBy: resolved.matchedBy, frameRecovered: false };
+        }
+
+        // 路径 2：复用 _activeFrame（微前端场景的核心优化）
+        if (this._activeFrame) {
+            // 探活：确认 frame 还能 evaluate（未被子应用卸载）
+            const alive = await this._activeFrame.evaluate(() => true).catch(() => false);
+            if (alive) {
+                return { frame: this._activeFrame, frameId: "active", matchedBy: "_activeFrame", frameRecovered: false };
+            }
+            // 失活：清空 _activeFrame，召回到 mainFrame
+            this._activeFrame = null;
+            return { frame: this.page.mainFrame(), frameId: "main", matchedBy: "_activeFrame failed, fallback to main", frameRecovered: true };
+        }
+
+        // 路径 3：mainFrame
+        const resolved = await this._resolveObserveFrame(step || {});
+        return { frame: resolved.frame, frameId: resolved.frameId, matchedBy: resolved.matchedBy, frameRecovered: false };
+    }
+
+    async _antSelect(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        let result = await adapter.select(frame, step.field || step.label, step.option || step.value, {
+            mode: step.mode,
+            timeout: step.timeout,
+        });
+
+        // 微前端跨 frame 浮层兜底：
+        // 如果当前 frame 未找到浮层选项（getPopupContainer 指向主文档），尝试主 frame
+        if (!result.acted && result.reason?.includes?.("not found in dropdown")) {
+            const mainFrame = this.page.mainFrame();
+            if (mainFrame !== frame) {
+                const retry = await adapter.select(mainFrame, step.field || step.label, step.option || step.value, {
+                    mode: step.mode,
+                    timeout: step.timeout,
+                });
+                if (retry.acted) {
+                    result = retry;
+                    result._dropdownFrame = "main";
+                }
+            }
+        }
+
+        this._lastActWasDropdown = true;
+        return { type: "antSelect", passed: result.acted && result.verified !== false, ...result };
+    }
+
+    async _antTreeSelect(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        let result = await adapter.treeSelect(frame, step.field || step.label, step.path || step.value, {
+            timeout: step.timeout,
+        });
+
+        // 微前端跨 frame 浮层兜底：同上
+        if (!result.acted && result.reason?.includes?.("node")) {
+            const mainFrame = this.page.mainFrame();
+            if (mainFrame !== frame) {
+                const retry = await adapter.treeSelect(mainFrame, step.field || step.label, step.path || step.value, { timeout: step.timeout });
+                if (retry.acted) {
+                    result = retry;
+                    result._dropdownFrame = "main";
+                }
+            }
+        }
+
+        this._lastActWasDropdown = true;
+        return { type: "antTreeSelect", passed: result.acted && result.verified !== false, ...result };
+    }
+
+    async _antInput(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const target = step.placeholder
+            ? { placeholder: step.placeholder }
+            : step.selector
+                ? { selector: step.selector }
+                : { label: step.field || step.label };
+        const result = await adapter.input(frame, target, step.value, { clear: step.clear });
+        return { type: "antInput", passed: result.acted, ...result };
+    }
+
+    async _antRadio(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.radio(frame, step.field || step.label, step.option || step.value);
+        return { type: "antRadio", passed: result.acted && result.verified, ...result };
+    }
+
+    async _antCheckbox(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.checkbox(frame, step.field || step.label, step.option, step.checked !== false);
+        return { type: "antCheckbox", passed: result.acted && result.verified, ...result };
+    }
+
+    async _antSwitch(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.switch(frame, step.field || step.label, step.on !== false);
+        return { type: "antSwitch", passed: result.acted && result.verified, ...result };
+    }
+
+    async _antDatePicker(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.datePicker(frame, step.field || step.label, step.value);
+        this._lastActWasDropdown = true;
+        return { type: "antDatePicker", passed: result.acted, ...result };
+    }
+
+    async _antCascader(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.cascader(frame, step.field || step.label, step.path || step.value, { timeout: step.timeout });
+        this._lastActWasDropdown = true;
+        return { type: "antCascader", passed: result.acted, ...result };
+    }
+
+    async _antUpload(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.upload(frame, step.field || step.label, step.filePath || step.value);
+        return { type: "antUpload", passed: result.acted, ...result };
+    }
+
+    async _formFill(step) {
+        const { frame } = await this._getTargetFrame(step);
+        const adapter = this._getAdapter(step.componentMeta);
+        const result = await adapter.formFill(frame, step.fields || [], { stepDelay: step.stepDelay });
+        const allOk = result.summary.failed === 0;
+        // 校验：可选地立即跑表单校验
+        if (step.validateAfter) {
+            const exp = createExpect({ frame, page: this.page });
+            const validation = await exp.validation().toPass({ timeout: step.validationTimeout ?? 2000 });
+            return {
+                type: "formFill",
+                passed: allOk && validation.passed,
+                ...result,
+                validation,
+            };
+        }
+        return { type: "formFill", passed: allOk, ...result };
+    }
+
+    async _closeAllDropdowns(step) {
+        const { frame } = await this._getTargetFrame(step || {});
+        const adapter = this._getAdapter();
+        // 微前端场景：同时清理主 frame 和所有子 frame 的浮层（修复 2 配套）
+        const result = await this._closeDropdownsAllFrames(frame);
+        this._lastActWasDropdown = false;
+        return { type: "closeAllDropdowns", passed: true, ...result };
+    }
+
+    /**
+     * 修复 2：跨 frame 浮层检测 — Ant 浮层可能渲染在子应用 iframe 内或父应用 document.body
+     * 同时清理当前 frame + 主 frame + 所有可访问子 frame 的浮层
+     */
+    async _closeDropdownsAllFrames(currentFrame) {
+        const adapter = this._getAdapter();
+        const mainFrame = this.page.mainFrame();
+        const allFrames = this.page.frames();
+        const closed = { perFrame: [], total: 0 };
+
+        // 优先清理当前 frame
+        const framesToClose = new Set([currentFrame, mainFrame, ...allFrames]);
+        for (const frame of framesToClose) {
+            try {
+                // 探活
+                const alive = await frame.evaluate(() => true).catch(() => false);
+                if (!alive) continue;
+                const r = await adapter.closeAllDropdowns(frame);
+                if (r?.closed) {
+                    closed.total += r.closed;
+                    closed.perFrame.push({ frameUrl: frame.url().slice(0, 100), closed: r.closed });
+                }
+            } catch {
+                // 跨域 iframe 无法 evaluate，跳过
+            }
+        }
+        return closed;
+    }
+
+    /**
+     * 通用 expect 断言：根据 step.assertion 路由到 expect.js 的不同断言方法
+     *
+     * 支持的 assertion：
+     *   - "locator.toBeVisible" / "toBeHidden" / "toBeEnabled" / "toHaveText" / "toHaveValue" / "toHaveCount" / "toHaveAttribute"
+     *   - "validation.toPass" / "validation.toHaveError"
+     *   - "url.toContain" / "url.toMatch"
+     *   - "api.toAllPass" / "api.toInclude" / "api.toHaveCount"
+     */
+    async _expect(step) {
+        const assertion = step.assertion;
+        const opts = { timeout: step.timeout, interval: step.interval };
+
+        if (!assertion) throw new Error("expect step requires assertion field");
+
+        // locator.* 系列
+        if (assertion.startsWith("locator.") || assertion.startsWith("toBe") || assertion.startsWith("toHave")) {
+            const { frame } = await this._getTargetFrame(step);
+            const loc = expectLocator(frame, step.selector);
+            const method = assertion.replace(/^locator\./, "");
+            if (typeof loc[method] !== "function") {
+                throw new Error(`Unknown locator assertion: ${method}`);
+            }
+            // toHaveText/toHaveValue/toHaveAttribute/toHaveCount 需要 expected 参数
+            const expected = step.expected ?? step.value ?? step.text ?? step.count;
+            const r = method === "toHaveAttribute"
+                ? await loc.toHaveAttribute(step.name, expected, opts)
+                : (expected !== undefined ? await loc[method](expected, opts) : await loc[method](opts));
+            return { type: "expect", ...r };
+        }
+
+        // validation.*
+        if (assertion.startsWith("validation.")) {
+            const { frame } = await this._getTargetFrame(step);
+            const val = expectValidation(frame);
+            const method = assertion.replace("validation.", "");
+            const r = method === "toHaveError"
+                ? await val.toHaveError(step.field || step.message, opts)
+                : await val.toPass(opts);
+            return { type: "expect", ...r };
+        }
+
+        // url.*
+        if (assertion.startsWith("url.")) {
+            const u = expectUrl(this.page);
+            const method = assertion.replace("url.", "");
+            const r = method === "toMatch"
+                ? await u.toMatch(step.regex || step.pattern, opts)
+                : await u.toContain(step.value || step.contains, opts);
+            return { type: "expect", ...r };
+        }
+
+        // api.*
+        if (assertion.startsWith("api.")) {
+            const capture = step.captureResult || this._lastApiCapture;
+            // 微前端：支持按 frame 范围过滤请求
+            // scope: "all"（默认，全 page）/ "current-frame"（仅 _activeFrame 同源）
+            let frameUrlContains = step.frameUrlContains;
+            if (!frameUrlContains && step.scope === "current-frame" && this._activeFrame) {
+                const url = this._activeFrame.url();
+                // blob: URL（wujie 子应用）取冒号后面的部分；http(s): URL 取 origin
+                if (url.startsWith("blob:")) {
+                    try { frameUrlContains = new URL(url.slice(5)).origin; } catch {}
+                } else {
+                    try { frameUrlContains = new URL(url).origin; } catch {}
+                }
+            }
+            const a = expectApi(capture, { scope: step.scope || "all", frameUrlContains });
+            const method = assertion.replace("api.", "");
+            if (typeof a[method] !== "function") {
+                throw new Error(`Unknown api assertion: ${method}`);
+            }
+            const r = method === "toInclude"
+                ? a.toInclude(step.urlPattern || step.pattern)
+                : method === "toHaveCount"
+                    ? a.toHaveCount(step.expected ?? step.count)
+                    : a[method]();
+            return { type: "expect", ...r };
+        }
+
+        throw new Error(`Unknown expect assertion: ${assertion}`);
+    }
+
     async _navigate(step) {
         const start = Date.now();
         // 微前端/SSO 重定向链场景：用 domcontentloaded 避免 page 对象被销毁
@@ -1773,6 +2102,148 @@ export class BrowserEngine {
         this.browser = null;
         this.page = null;
     }
+
+    /**
+     * 执行测试用例：支持 dataset 参数化、变量替换
+     * @param {object} testCase - 用例配置
+     * @param {object} context - 执行上下文
+     * @returns {Promise<object>} 用例执行结果摘要
+     */
+    async executeTestCase(testCase, context = {}) {
+        const startTime = Date.now();
+        const results = [];
+        const dataset = testCase.dataset || [{ __row: 0 }];
+
+        // setup 阶段：frame 预定位
+        if (testCase.setup?.findFrame && !this._activeFrame) {
+            const resolved = await this._resolveObserveFrame(testCase.setup.findFrame);
+            this._activeFrame = resolved.frame;
+        }
+
+        for (let dataRowIndex = 0; dataRowIndex < dataset.length; dataRowIndex++) {
+            const dataRow = dataset[dataRowIndex];
+            const rowStartTime = Date.now();
+            const rowResults = [];
+            let allPassed = true;
+
+            for (let stepIndex = 0; stepIndex < testCase.steps.length; stepIndex++) {
+                const rawStep = testCase.steps[stepIndex];
+                // 变量替换：{{key}} → dataRow[key]
+                const step = this._substituteVariables(rawStep, dataRow);
+
+                // 微前端 frame 探活召回：每次 step 执行前确认 _activeFrame 仍然有效
+                // 如果失效（子应用卸载/路由切换），尝试用 setup.findFrame 重新定位
+                if (this._activeFrame) {
+                    const alive = await this._activeFrame.evaluate(() => true).catch(() => false);
+                    if (!alive) {
+                        this._activeFrame = null;
+                        if (testCase.setup?.findFrame) {
+                            const recovered = await this._resolveObserveFrame(testCase.setup.findFrame).catch(() => null);
+                            if (recovered?.frame) {
+                                this._activeFrame = recovered.frame;
+                                rowResults.push({
+                                    type: "frameRecover",
+                                    status: "PASS",
+                                    duration: 0,
+                                    stepIndex,
+                                    dataRowIndex,
+                                    matchedBy: recovered.matchedBy,
+                                    reason: "auto-recovered from frame loss",
+                                });
+                                results.push(rowResults[rowResults.length - 1]);
+                            }
+                        }
+                    }
+                }
+
+                const stepResult = await this.executeStep(step, context);
+
+                rowResults.push({
+                    ...stepResult,
+                    stepIndex,
+                    dataRowIndex,
+                    dataRow: Object.fromEntries(Object.entries(dataRow).map(([k]) => [k, String(dataRow[k]).slice(0, 80)])),
+                });
+                results.push(rowResults[rowResults.length - 1]);
+
+                if (stepResult.status === "FAIL") {
+                    allPassed = false;
+                    const recovery = testCase.recovery || {};
+                    const maxRetries = recovery.maxRetriesPerStep ?? 0;
+                    for (let retry = 0; retry < maxRetries; retry++) {
+                        const retryResult = await this.executeStep(step, context);
+                        rowResults.push({
+                            ...retryResult,
+                            stepIndex,
+                            dataRowIndex,
+                            retry: retry + 1,
+                        });
+                        results.push(rowResults[rowResults.length - 1]);
+                        if (retryResult.status === "PASS") {
+                            allPassed = true;
+                            break;
+                        }
+                    }
+                    if (!allPassed && step.continueOnFail === false) break;
+                }
+
+                // frame 切换：如果 step 设置了新 frame，后续步骤默认走新 frame
+                if (step.findFrame || step.frameContentContains || step.frameUrlContains) {
+                    const resolved = await this._resolveObserveFrame(step);
+                    this._activeFrame = resolved.frame;
+                }
+            }
+
+            rowResults.duration = Date.now() - rowStartTime;
+            rowResults.passed = allPassed;
+        }
+
+        const duration = Date.now() - startTime;
+        const passed = results.filter((r) => r.status === "PASS").length;
+        const failed = results.filter((r) => r.status === "FAIL").length;
+
+        return {
+            title: testCase.title,
+            datasetSize: dataset.length,
+            totalSteps: results.length,
+            passedSteps: passed,
+            failedSteps: failed,
+            passed: failed === 0,
+            duration,
+            results,
+            summary: {
+                perDataset: results.reduce((acc, r) => {
+                    const key = r.dataRowIndex;
+                    if (!acc[key]) acc[key] = { passed: 0, failed: 0, duration: 0 };
+                    if (r.status === "PASS") acc[key].passed++;
+                    else acc[key].failed++;
+                    acc[key].duration += r.duration;
+                    return acc;
+                }, {}),
+            },
+        };
+    }
+
+    /**
+     * 递归替换对象中的 {{varName}} 变量
+     */
+    _substituteVariables(obj, dataRow) {
+        if (typeof obj === "string") {
+            return obj.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
+                const keys = key.split(".");
+                let val = dataRow;
+                for (const k of keys) val = val?.[k];
+                return val !== undefined ? (typeof val === "string" ? val : String(val)) : "";
+            });
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this._substituteVariables(item, dataRow));
+        }
+        if (obj && typeof obj === "object") {
+            return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, this._substituteVariables(v, dataRow)]));
+        }
+        return obj;
+    }
 }
 
 /**