@szc-ft/mcp-szcd-client 0.27.3 → 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);
@@ -269,12 +297,28 @@ export class BrowserEngine {
                     .filter(isCandidate);
             }
 
+            function isVisibleEnabled(el) {
+                const rect = el.getBoundingClientRect();
+                const style = window.getComputedStyle(el);
+                if (rect.width <= 0 || rect.height <= 0) return false;
+                if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
+                if (el.disabled || el.getAttribute("aria-disabled") === "true") return false;
+                return true;
+            }
+
             function findBySelector(selector) {
                 if (!selector) return null;
                 if (selector.startsWith("text=")) {
                     const expected = selector.slice(5).trim();
-                    return interactiveElements().find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected)) ||
-                        Array.from(document.querySelectorAll("*")).find((el) => getText(el).includes(expected));
+                    // 默认仅匹配 visible+enabled 元素，避免命中 ant-select 的隐藏 input、收起菜单里的 li
+                    // 需要包含隐藏元素时显式 includeHidden=true
+                    const includeHidden = actOptions.includeHidden === true;
+                    const filter = (el) => includeHidden || isVisibleEnabled(el);
+                    const interactive = interactiveElements().filter(filter);
+                    let hit = interactive.find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected));
+                    if (hit) return hit;
+                    const all = Array.from(document.querySelectorAll("*")).filter(filter);
+                    return all.find((el) => getText(el).includes(expected)) || null;
                 }
                 if (selector.startsWith("role=")) {
                     const match = selector.match(/^role=([^\[]+)(?:\[name="([^"]+)"\])?/);
@@ -357,6 +401,7 @@ export class BrowserEngine {
             action,
             typeText,
             clear: Boolean(options.clear),
+            includeHidden: Boolean(options.includeHidden),
         });
 
         if (!result.found) {
@@ -385,140 +430,207 @@ export class BrowserEngine {
             ? options.menuPath
             : String(options.menuPath).split("/").map((item) => item.trim()).filter(Boolean);
         const waitAfterEach = Number.parseInt(options.waitAfterEach ?? 300, 10);
+        const drawerTriggerSelector = options.drawerTriggerSelector || null;
+        const drawerOpenSelector = options.drawerOpenSelector || ".ant-drawer-open, .ant-drawer.ant-drawer-open";
+        const scrollContainerSelector = options.menuScrollContainer || null;
+        const useNativeHover = options.useNativeHover !== false; // 默认开
+        const maxRetryPerStep = Number.parseInt(options.maxRetryPerStep ?? 2, 10);
 
         if (menuPath.length === 0) {
             throw new Error("menuPath is empty");
         }
 
-        const result = await targetFrame.frame.evaluate(async (pathItems, waitMs) => {
-            function sleep(ms) {
-                return new Promise((resolve) => setTimeout(resolve, ms));
-            }
-
-            function textOf(el) {
-                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim();
-            }
+        const frame = targetFrame.frame;
 
-            function classText(el) {
-                return typeof el.className === "string" ? el.className : "";
-            }
-
-            function isVisible(el) {
-                const rect = el.getBoundingClientRect();
-                const style = window.getComputedStyle(el);
-                return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
-            }
-
-            function menuCandidates() {
-                return Array.from(document.querySelectorAll([
-                    "[role='menuitem']",
-                    ".ant-menu-item",
-                    ".ant-menu-submenu-title",
-                    "li[class*='menu']",
-                    "a",
-                    "button",
-                    "[class*='menu-item']",
-                    "[class*='submenu']",
-                ].join(","))).filter(isVisible);
-            }
-
-            function scoreCandidate(el, text, level) {
-                const actual = textOf(el);
-                if (!actual) return -1;
-                let score = -1;
-                if (actual === text) score = 100;
-                else if (actual.includes(text)) score = 70;
-                else if (text.includes(actual)) score = 50;
-                if (score < 0) return -1;
-                const cls = classText(el);
-                const role = el.getAttribute("role") || "";
-                if (role === "menuitem") score += 10;
-                if (cls.includes("ant-menu-submenu-title")) score += level < pathItems.length - 1 ? 20 : -5;
-                if (cls.includes("ant-menu-item")) score += level === pathItems.length - 1 ? 20 : 0;
-                if (cls.includes("ant-menu-item-selected")) score += 5;
-                return score;
-            }
+        const ensureDrawerOpen = async () => {
+            if (!drawerTriggerSelector) return { ensured: false, reason: "no drawer" };
+            const isOpen = await frame.evaluate((sel) => !!document.querySelector(sel), drawerOpenSelector).catch(() => false);
+            if (isOpen) return { ensured: true, reason: "already open" };
+            const triggered = await frame.evaluate((sel) => {
+                const el = document.querySelector(sel);
+                if (!el) return false;
+                el.scrollIntoView({ block: "center", inline: "center" });
+                el.click();
+                return true;
+            }, drawerTriggerSelector).catch(() => false);
+            if (!triggered) return { ensured: false, reason: "trigger not found" };
+            await new Promise((r) => setTimeout(r, waitAfterEach));
+            return { ensured: true, reason: "clicked trigger" };
+        };
 
-            function findMenuItem(text, level) {
-                return menuCandidates()
-                    .map((el) => ({ el, score: scoreCandidate(el, text, level), text: textOf(el) }))
-                    .filter((item) => item.score >= 0)
-                    .sort((a, b) => b.score - a.score)[0] || null;
-            }
+        const scrollContainerOnce = async () => {
+            if (!scrollContainerSelector) return false;
+            return frame.evaluate((sel) => {
+                const c = document.querySelector(sel);
+                if (!c) return false;
+                c.scrollTop = Math.min(c.scrollTop + Math.max(c.clientHeight - 40, 200), c.scrollHeight);
+                return true;
+            }, scrollContainerSelector).catch(() => false);
+        };
 
-            function elementSnapshot(el) {
-                const rect = el.getBoundingClientRect();
+        const findStep = async (text, level) => {
+            return frame.evaluate((expectedText, lvl, totalLevels) => {
+                function textOf(el) {
+                    return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim();
+                }
+                function classText(el) {
+                    return typeof el.className === "string" ? el.className : "";
+                }
+                function isVisible(el) {
+                    const rect = el.getBoundingClientRect();
+                    const style = window.getComputedStyle(el);
+                    return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+                }
+                function menuCandidates() {
+                    return Array.from(document.querySelectorAll([
+                        "[role='menuitem']",
+                        ".ant-menu-item",
+                        ".ant-menu-submenu-title",
+                        "li[class*='menu']",
+                        "a",
+                        "button",
+                        "[class*='menu-item']",
+                        "[class*='submenu']",
+                    ].join(","))).filter(isVisible);
+                }
+                function score(el) {
+                    const actual = textOf(el);
+                    if (!actual) return -1;
+                    let s = -1;
+                    if (actual === expectedText) s = 100;
+                    else if (actual.includes(expectedText)) s = 70;
+                    else if (expectedText.includes(actual)) s = 50;
+                    if (s < 0) return -1;
+                    const cls = classText(el);
+                    const role = el.getAttribute("role") || "";
+                    if (role === "menuitem") s += 10;
+                    if (cls.includes("ant-menu-submenu-title")) s += lvl < totalLevels - 1 ? 20 : -5;
+                    if (cls.includes("ant-menu-item")) s += lvl === totalLevels - 1 ? 20 : 0;
+                    if (cls.includes("ant-menu-item-selected")) s += 5;
+                    return s;
+                }
+                const ranked = menuCandidates()
+                    .map((el) => ({ el, s: score(el), text: textOf(el) }))
+                    .filter((x) => x.s >= 0)
+                    .sort((a, b) => b.s - a.s);
+                const top = ranked[0];
+                if (!top) {
+                    return {
+                        found: false,
+                        candidates: menuCandidates().slice(0, 8).map((el) => ({
+                            text: textOf(el).slice(0, 80),
+                            className: classText(el).slice(0, 120),
+                        })),
+                    };
+                }
+                // 用稳定 attr 标记，避免后续 click 时 ranking 漂移
+                top.el.setAttribute("data-szcd-menu-target", "1");
+                const rect = top.el.getBoundingClientRect();
                 return {
-                    tagName: el.tagName,
-                    text: textOf(el).slice(0, 120),
-                    role: el.getAttribute("role") || null,
-                    className: classText(el),
-                    ariaExpanded: el.getAttribute("aria-expanded"),
+                    found: true,
+                    matchedText: top.text,
                     bbox: {
-                        x: Math.round(rect.x),
-                        y: Math.round(rect.y),
-                        width: Math.round(rect.width),
-                        height: Math.round(rect.height),
+                        x: Math.round(rect.x), y: Math.round(rect.y),
+                        width: Math.round(rect.width), height: Math.round(rect.height),
+                    },
+                    snapshot: {
+                        tagName: top.el.tagName,
+                        text: textOf(top.el).slice(0, 120),
+                        role: top.el.getAttribute("role") || null,
+                        className: classText(top.el),
+                        ariaExpanded: top.el.getAttribute("aria-expanded"),
                     },
                 };
-            }
-
-            const steps = [];
-
-            for (let i = 0; i < pathItems.length; i++) {
-                const text = pathItems[i];
-                let match = findMenuItem(text, i);
-                if (!match && i > 0) {
-                    await sleep(waitMs * 2);
-                    match = findMenuItem(text, i);
-                }
-                if (!match) {
-                    return { found: false, failedAt: text, steps };
-                }
+            }, text, level, menuPath.length).catch(() => ({ found: false, candidates: [] }));
+        };
 
-                const el = match.el;
+        const clickStep = async (isLast) => {
+            return frame.evaluate(async (waitMs, last) => {
+                const el = document.querySelector("[data-szcd-menu-target='1']");
+                if (!el) return { performed: false, error: "marker lost" };
                 el.scrollIntoView({ block: "center", inline: "center" });
                 const beforeUrl = location.href;
                 const beforeText = document.body?.innerText || "";
-                const isLast = i === pathItems.length - 1;
-                const before = elementSnapshot(el);
-
-                el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
-                el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
                 el.click();
-                await sleep(waitMs);
-
-                const afterClass = classText(el);
-                const afterExpanded = el.getAttribute("aria-expanded");
-                steps.push({
-                    text,
-                    action: isLast ? "click" : "expand",
-                    status: "PASS",
-                    matchedText: match.text,
-                    before,
+                el.removeAttribute("data-szcd-menu-target");
+                await new Promise((r) => setTimeout(r, waitMs));
+                const cls = typeof el.className === "string" ? el.className : "";
+                return {
+                    performed: true,
+                    action: last ? "click" : "expand",
                     after: {
-                        className: afterClass,
-                        ariaExpanded: afterExpanded,
+                        className: cls,
+                        ariaExpanded: el.getAttribute("aria-expanded"),
                         urlChanged: location.href !== beforeUrl,
                         textChanged: (document.body?.innerText || "") !== beforeText,
-                        selected: afterClass.includes("selected") || afterClass.includes("active"),
+                        selected: cls.includes("selected") || cls.includes("active"),
                     },
-                });
+                };
+            }, waitAfterEach, isLast);
+        };
+
+        const steps = [];
+
+        for (let i = 0; i < menuPath.length; i++) {
+            const text = menuPath[i];
+            const isLast = i === menuPath.length - 1;
+
+            // 抽屉式菜单：每级前都先确认抽屉是开的
+            const drawerState = await ensureDrawerOpen();
+
+            let match = await findStep(text, i);
+            let attempts = 0;
+            while (!match.found && attempts < maxRetryPerStep) {
+                attempts += 1;
+                // 滚动一次再找
+                const scrolled = await scrollContainerOnce();
+                if (!scrolled) await new Promise((r) => setTimeout(r, waitAfterEach));
+                match = await findStep(text, i);
             }
 
-            return {
-                found: true,
-                performed: true,
-                steps,
-                currentUrl: location.href,
-                title: document.title,
-            };
-        }, menuPath, waitAfterEach);
+            if (!match.found) {
+                return {
+                    acted: false,
+                    action: "menuPath",
+                    menuPath,
+                    target: {
+                        frameId: targetFrame.frameId,
+                        frameUrl: targetFrame.frame.url(),
+                        matchedBy: targetFrame.matchedBy,
+                    },
+                    failedAt: text,
+                    failedAtIndex: i,
+                    candidates: match.candidates || [],
+                    drawerState,
+                    steps,
+                };
+            }
 
-        if (!result.found) {
-            throw new Error(`Menu path item not found: ${result.failedAt}`);
+            // native hover（puppeteer frame.hover），优于 dispatchEvent
+            if (useNativeHover && typeof frame.hover === "function") {
+                try {
+                    await frame.hover("[data-szcd-menu-target='1']");
+                } catch {
+                    // hover 失败不致命，继续 click
+                }
+            }
+
+            const clickRes = await clickStep(isLast);
+            steps.push({
+                text,
+                action: clickRes.action || (isLast ? "click" : "expand"),
+                status: clickRes.performed ? "PASS" : "FAIL",
+                matchedText: match.matchedText,
+                before: match.snapshot,
+                after: clickRes.after || null,
+                drawerEnsured: drawerState.ensured,
+                retries: attempts,
+            });
         }
 
+        const currentUrl = this.page.url();
+        const title = await this.page.title().catch(() => "");
+
         return {
             acted: true,
             action: "menuPath",
@@ -528,9 +640,9 @@ export class BrowserEngine {
                 frameUrl: targetFrame.frame.url(),
                 matchedBy: targetFrame.matchedBy,
             },
-            steps: result.steps,
-            currentUrl: result.currentUrl,
-            title: result.title,
+            steps,
+            currentUrl,
+            title,
         };
     }
 
@@ -603,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),
@@ -670,7 +785,7 @@ export class BrowserEngine {
         });
 
         const pageTarget = this.page.target();
-        const attachCandidates = this.browser.targets().filter((target) => {
+        const pickCandidates = () => this.browser.targets().filter((target) => {
             if (target === pageTarget) return false;
             if (!["iframe", "page"].includes(target.type())) return false;
             const targetUrl = target.url() || "";
@@ -681,15 +796,33 @@ export class BrowserEngine {
             return true;
         });
 
-        for (const target of attachCandidates) {
-            const session = await target.createCDPSession().catch(() => null);
-            if (!session) continue;
-            await addSession(session, {
-                id: target.url() || `${target.type()}-${targets.length}`,
-                type: target.type(),
-                url: target.url() || "",
-                matchedBy: "browser.targets",
-            });
+        const attachOnce = async (candidates) => {
+            for (const target of candidates) {
+                const session = await target.createCDPSession().catch(() => null);
+                if (!session) continue;
+                await addSession(session, {
+                    id: target.url() || `${target.type()}-${targets.length}`,
+                    type: target.type(),
+                    url: target.url() || "",
+                    matchedBy: "browser.targets",
+                });
+            }
+        };
+
+        // 微前端 wujie/qiankun 时序：iframe target 可能在主页面 ready 后才注册
+        // attach=0 时延迟重试，最多 3 次（含首次）
+        const maxAttachTries = Number.parseInt(options.attachRetries ?? 3, 10);
+        const attachRetryDelay = Number.parseInt(options.attachRetryDelay ?? 1500, 10);
+        let attachCandidates = pickCandidates();
+        let tries = 1;
+        await attachOnce(attachCandidates);
+        const attachLog = [{ try: 1, count: attachCandidates.length }];
+        while (attachCandidates.length === 0 && tries < maxAttachTries) {
+            tries += 1;
+            await new Promise((r) => setTimeout(r, attachRetryDelay));
+            attachCandidates = pickCandidates();
+            attachLog.push({ try: tries, count: attachCandidates.length });
+            await attachOnce(attachCandidates);
         }
 
         if (options.reload) {
@@ -723,6 +856,7 @@ export class BrowserEngine {
                 success: requestList.length - failed.length,
                 failed: failed.length,
                 targets: targets.length,
+                attachLog,
                 duration: Date.now() - startedAt,
             },
         };
@@ -1021,11 +1155,311 @@ export class BrowserEngine {
             case "findFrame":    return this._findFrame(step);
             case "loginWait":    return this._loginWait(step);
             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 对象被销毁
@@ -1435,6 +1869,205 @@ export class BrowserEngine {
         };
     }
 
+    /**
+     * 高层 runner：把"批量探索动态菜单 + 抓接口 + 出报告"打包成一个 step。
+     * 当前仅支持 task='menu-api-scan'，对应反馈中"129 路由全覆盖"场景。
+     *
+     * options:
+     *   task: "menu-api-scan"
+     *   menuApiPattern (string|RegExp 默认 /listUserViewMenus/) — 用作 _discoverMenus 的 lastApiCapture 过滤
+     *   menuLimit (number 默认 0=不限) — 仅探索前 N 条
+     *   menuPathPrefix (Array<string>) — 仅探索 path 开头匹配的菜单
+     *   menuFilter (Array<string>) — 仅探索 name/path 包含任一关键字的菜单
+     *   drawerTriggerSelector / drawerOpenSelector / menuScrollContainer / useNativeHover / maxRetryPerStep — 透传 _actMenuPath
+     *   apiCaptureOptions (object) — 透传 captureApi
+     *   continueOnFail (bool 默认 true)
+     *   snapshotEach (bool 默认 false) — 每条菜单后做轻量 observe
+     *   screenshotEach (bool 默认 false) — 失败时截图（依赖 context.outputDir）
+     */
+    async runTask(step, context = {}) {
+        const taskName = step.task || step.name || "menu-api-scan";
+        if (taskName !== "menu-api-scan") {
+            return { task: taskName, supported: false, error: `Unsupported task: ${taskName}` };
+        }
+
+        const menus = await this._discoverMenus(step, context);
+        if (!menus.length) {
+            return {
+                task: taskName,
+                discovered: 0,
+                error: "No menus discovered. Run apiCapture targeting menuApiPattern first, or provide step.menus directly.",
+            };
+        }
+
+        const limit = Number.parseInt(step.menuLimit ?? 0, 10);
+        const candidates = limit > 0 ? menus.slice(0, limit) : menus;
+        const continueOnFail = step.continueOnFail !== false;
+        const startedAt = Date.now();
+        const results = [];
+        const byOutcome = { clickFailed: 0, noApi: 0, apiOk: 0, apiFailed: 0 };
+
+        for (let i = 0; i < candidates.length; i += 1) {
+            const menu = candidates[i];
+            const itemStartedAt = Date.now();
+            const item = {
+                index: i,
+                menu: { path: menu.path, name: menu.name, names: menu.names },
+                outcome: null,
+            };
+
+            // 1. 点菜单链路（走 act 顶层入口，让它先 _resolveObserveFrame 再分发到 _actMenuPath）
+            const menuStep = {
+                menuPath: menu.names,
+                drawerTriggerSelector: step.drawerTriggerSelector,
+                drawerOpenSelector: step.drawerOpenSelector,
+                menuScrollContainer: step.menuScrollContainer,
+                useNativeHover: step.useNativeHover,
+                maxRetryPerStep: step.maxRetryPerStep,
+                stepDelay: step.stepDelay,
+                frameContentContains: step.frameContentContains,
+                frameUrlContains: step.frameUrlContains,
+                frameIndex: step.frameIndex,
+            };
+            let menuResult;
+            try {
+                menuResult = await this.act(menuStep);
+            } catch (err) {
+                menuResult = { acted: false, error: err.message };
+            }
+            item.menuResult = menuResult;
+
+            if (!menuResult || menuResult.acted === false) {
+                item.outcome = "clickFailed";
+                byOutcome.clickFailed += 1;
+                if (step.screenshotEach) {
+                    try {
+                        const shot = await this._screenshot({ filename: `runTask-fail-${i}.png`, fullPage: true }, context);
+                        item.screenshot = shot;
+                    } catch {
+                        // ignore
+                    }
+                }
+                results.push({ ...item, durationMs: Date.now() - itemStartedAt });
+                if (!continueOnFail) break;
+                continue;
+            }
+
+            // 2. 抓接口
+            const apiStep = {
+                type: "apiCapture",
+                ...(step.apiCaptureOptions || {}),
+                wait: step.apiCaptureOptions?.wait ?? 4000,
+            };
+            let apiResult;
+            try {
+                apiResult = await this.captureApi(apiStep);
+            } catch (err) {
+                apiResult = { error: err.message, summary: { total: 0, failed: 0 } };
+            }
+            item.api = apiResult;
+
+            const total = apiResult?.summary?.total ?? 0;
+            const failed = apiResult?.summary?.failed ?? 0;
+            if (total === 0) {
+                item.outcome = "noApi";
+                byOutcome.noApi += 1;
+            } else if (failed > 0) {
+                item.outcome = "apiFailed";
+                byOutcome.apiFailed += 1;
+            } else {
+                item.outcome = "apiOk";
+                byOutcome.apiOk += 1;
+            }
+
+            if (step.snapshotEach) {
+                try {
+                    item.snapshot = await this.observe({ headingsOnly: true });
+                } catch {
+                    // ignore
+                }
+            }
+
+            results.push({ ...item, durationMs: Date.now() - itemStartedAt });
+        }
+
+        return {
+            task: taskName,
+            discovered: menus.length,
+            attempted: results.length,
+            durationMs: Date.now() - startedAt,
+            byOutcome,
+            results,
+        };
+    }
+
+    /**
+     * 从 lastApiCapture 中找菜单接口响应（默认 /listUserViewMenus/），
+     * 用 CDP getResponseBody 拿到 body 后递归拍平。
+     * 兜底：如果 step.menus 已显式传入，直接用之。
+     */
+    async _discoverMenus(step = {}, context = {}) {
+        if (Array.isArray(step.menus) && step.menus.length) {
+            return this._flattenMenuTree(step.menus, step.menuPathPrefix, step.menuFilter);
+        }
+
+        const lastCapture = step.captureResult || context.lastApiCapture;
+        if (!lastCapture?.requests?.length) return [];
+
+        const patternRaw = step.menuApiPattern ?? "listUserViewMenus";
+        const pattern = patternRaw instanceof RegExp ? patternRaw : new RegExp(patternRaw);
+        const candidate = lastCapture.requests.find((r) => pattern.test(r.url || ""));
+        if (!candidate) return [];
+
+        let tree = candidate.responseBody;
+        if (typeof tree === "string") {
+            try { tree = JSON.parse(tree); } catch { return []; }
+        }
+        // 常见包装：{ data: [...] } / { result: { data: [...] } }
+        const list =
+            (Array.isArray(tree) && tree) ||
+            tree?.data ||
+            tree?.result?.data ||
+            tree?.result ||
+            [];
+        return this._flattenMenuTree(list, step.menuPathPrefix, step.menuFilter);
+    }
+
+    /**
+     * 把菜单树拍平成可点击的链路：
+     *   { path, name, names: [一级名, 二级名, ...], depth }
+     * children 字段名兼容 children/subMenus/sub。
+     */
+    _flattenMenuTree(tree, pathPrefix, keywords) {
+        const out = [];
+        const prefixes = Array.isArray(pathPrefix) ? pathPrefix : pathPrefix ? [pathPrefix] : null;
+        const kws = Array.isArray(keywords) ? keywords : keywords ? [keywords] : null;
+
+        const visit = (nodes, parentNames) => {
+            if (!Array.isArray(nodes)) return;
+            for (const node of nodes) {
+                if (!node) continue;
+                const name = node.name || node.title || node.label || node.menuName;
+                const path = node.path || node.url || node.route;
+                const names = name ? [...parentNames, name] : parentNames.slice();
+                const children = node.children || node.subMenus || node.sub || node.childs;
+
+                // 叶子节点（无 children 或 children 空）才有意义点击触发请求
+                const isLeaf = !Array.isArray(children) || children.length === 0;
+                if (isLeaf && name && path) {
+                    let keep = true;
+                    if (prefixes && !prefixes.some((p) => path.startsWith(p))) keep = false;
+                    if (keep && kws && !kws.some((k) => name.includes(k) || path.includes(k))) keep = false;
+                    if (keep) out.push({ path, name, names, depth: names.length });
+                } else if (Array.isArray(children) && children.length) {
+                    visit(children, names);
+                }
+            }
+        };
+        visit(tree, []);
+        return out;
+    }
+
     _resolveSelector(selector) {
         if (!selector) return selector;
         // ~.editKnowledge → [class*="editKnowledge"]
@@ -1469,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;
+    }
 }
 
 /**