@szc-ft/mcp-szcd-client 0.28.1 → 0.28.2

package/standard-skill/local-browser-test/lib/chrome-finder.js

@@ -0,0 +1,125 @@
+/**
+ * Chrome 路径检测 - 跨平台查找 Chrome/Chromium 可执行文件
+ * 仅 launch 模式需要，connect 模式通过 CDP 连接不需要此模块
+ */
+
+import fs from "node:fs";
+import { execSync } from "node:child_process";
+import os from "node:os";
+
+/**
+ * 跨平台 Chrome 路径候选列表
+ */
+const CHROME_PATHS = {
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/snap/bin/chromium",
+        "/usr/local/bin/chrome",
+    ],
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        `${process.env.LOCALAPPDATA || ""}\\Google\\Chrome\\Application\\chrome.exe`,
+    ],
+};
+
+/**
+ * 通过 PATH 搜索命令
+ * @param {string} cmd - 命令名
+ * @returns {string|null}
+ */
+function findInPath(cmd) {
+    try {
+        const platform = os.platform();
+        const command = platform === "win32" ? `where ${cmd}` : `which ${cmd}`;
+        const result = execSync(command, { encoding: "utf8", timeout: 5000 }).trim();
+        const firstLine = result.split("\n")[0].trim();
+        if (firstLine && fs.existsSync(firstLine)) {
+            return firstLine;
+        }
+    } catch {
+        // not found
+    }
+    return null;
+}
+
+/**
+ * 查找本地 Chrome 浏览器路径
+ * @returns {{ path: string|null, name: string, error?: string }}
+ */
+export function findChrome() {
+    const platform = os.platform();
+    const candidates = CHROME_PATHS[platform] || CHROME_PATHS.linux;
+
+    // 1. 检查已知路径
+    for (const p of candidates) {
+        if (p && fs.existsSync(p)) {
+            const name = p.includes("Chromium") ? "Chromium" :
+                         p.includes("Canary") ? "Chrome Canary" : "Google Chrome";
+            return { path: p, name };
+        }
+    }
+
+    // 2. PATH 搜索
+    const pathCmds = platform === "win32"
+        ? ["chrome", "chromium"]
+        : ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"];
+
+    for (const cmd of pathCmds) {
+        const found = findInPath(cmd);
+        if (found) {
+            const name = cmd.includes("chromium") ? "Chromium" : "Google Chrome";
+            return { path: found, name };
+        }
+    }
+
+    // 3. 未找到
+    return {
+        path: null,
+        name: "unknown",
+        error: "CHROME_NOT_FOUND",
+    };
+}
+
+/**
+ * 获取 Chrome 未找到时的安装引导信息
+ * @returns {object}
+ */
+export function getChromeInstallGuide() {
+    const platform = os.platform();
+    const guides = {
+        linux: {
+            message: "未检测到 Chrome/Chromium 浏览器",
+            installCommands: [
+                "Ubuntu/Debian: sudo apt install google-chrome-stable",
+                "Ubuntu/Debian (Chromium): sudo apt install chromium-browser",
+                "CentOS/RHEL: sudo yum install google-chrome-stable",
+            ],
+        },
+        darwin: {
+            message: "未检测到 Chrome/Chromium 浏览器",
+            installCommands: [
+                "Homebrew: brew install --cask google-chrome",
+                "或从 https://www.google.com/chrome/ 下载",
+            ],
+        },
+        win32: {
+            message: "未检测到 Chrome 浏览器",
+            installCommands: [
+                "从 https://www.google.com/chrome/ 下载安装",
+                "或 winget install Google.Chrome",
+            ],
+        },
+    };
+    return guides[platform] || guides.linux;
+}
+
+export default { findChrome, getChromeInstallGuide };

package/standard-skill/local-browser-test/lib/expect.js

@@ -0,0 +1,392 @@
+/**
+ * 语义断言层 — Playwright expect.poll 风格
+ *
+ * 设计目标：把"15×200ms 硬循环 + ad-hoc checkElement"统一成 Promise 风格的可组合断言。
+ * 所有断言返回 { passed, reason, actual, expected, duration }，可直接进测试报告。
+ *
+ * 用法：
+ *   const exp = createExpect(engine);
+ *   await exp.poll(() => frame.$$eval(".ant-select-item-option", els => els.length > 0));
+ *   await exp.locator(frame, "text=提交").toBeVisible({ timeout: 3000 });
+ *   await exp.validation(frame).toPass();
+ *   await exp.url(page).toContain("/catalog/list");
+ *   await exp.api(captureResult).toAllPass();
+ */
+
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_INTERVAL = 200;
+
+/**
+ * 轮询直到 predicate 返回 truthy，否则超时
+ * @param {Function} predicate - 异步函数，返回值参与判定
+ * @param {object} options - { timeout, interval, message }
+ * @returns {Promise<{ passed, value, attempts, duration }>}
+ */
+export async function poll(predicate, options = {}) {
+    const timeout = Number.parseInt(options.timeout ?? DEFAULT_TIMEOUT, 10);
+    const interval = Number.parseInt(options.interval ?? DEFAULT_INTERVAL, 10);
+    const start = Date.now();
+    let attempts = 0;
+    let lastValue;
+    let lastError;
+
+    while (Date.now() - start < timeout) {
+        attempts += 1;
+        try {
+            lastValue = await predicate();
+            if (lastValue) {
+                return {
+                    passed: true,
+                    value: lastValue,
+                    attempts,
+                    duration: Date.now() - start,
+                };
+            }
+        } catch (err) {
+            lastError = err;
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+
+    return {
+        passed: false,
+        value: lastValue,
+        attempts,
+        duration: Date.now() - start,
+        reason: lastError
+            ? `predicate threw: ${lastError.message}`
+            : options.message || `poll timeout after ${timeout}ms (last value: ${JSON.stringify(lastValue)?.slice(0, 200)})`,
+    };
+}
+
+/**
+ * 元素定位断言器：locator(frame, selector) 返回带 toXxx 的对象
+ * selector 支持 text= / role= / ~xxx / 普通 CSS
+ */
+export function locator(frame, selector) {
+    /**
+     * 在 frame 内查找匹配 selector 的第一个元素，返回该元素的可观测状态。
+     * 一次 evaluate 取齐所有状态，避免多次 round-trip。
+     */
+    async function probe() {
+        return frame.evaluate((sel) => {
+            function resolveSelector(s) {
+                if (!s) return null;
+                if (s.startsWith("~")) {
+                    const cls = s.slice(1).replace(/^\./, "");
+                    return `[class*="${cls}"]`;
+                }
+                return s;
+            }
+            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"
+                    && Number(style.opacity) !== 0;
+            }
+            function isEnabled(el) {
+                return !el.disabled && el.getAttribute("aria-disabled") !== "true";
+            }
+            function findText(text) {
+                const candidates = Array.from(document.querySelectorAll(
+                    "a,button,input,select,textarea,summary,span,div,label,[role],[data-testid]"
+                ));
+                return candidates.find((el) => {
+                    if (!isVisible(el)) return false;
+                    const t = (el.innerText || el.textContent || "").trim();
+                    return t.includes(text);
+                });
+            }
+            function findRole(roleSpec) {
+                const match = roleSpec.match(/^([^\[]+)(?:\[name="([^"]+)"\])?/);
+                const role = match?.[1]?.trim();
+                const name = match?.[2]?.trim();
+                const all = Array.from(document.querySelectorAll(`[role="${role}"]`));
+                return all.find((el) => {
+                    if (!isVisible(el)) return false;
+                    if (!name) return true;
+                    const t = (el.innerText || el.textContent || "").trim();
+                    return t.includes(name) || (el.getAttribute("aria-label") || "").includes(name);
+                });
+            }
+
+            let el = null;
+            if (sel.startsWith("text=")) {
+                el = findText(sel.slice(5).trim().replace(/^["']|["']$/g, ""));
+            } else if (sel.startsWith("role=")) {
+                el = findRole(sel.slice(5));
+            } else {
+                try { el = document.querySelector(resolveSelector(sel)); } catch { el = null; }
+            }
+
+            if (!el) return { found: false };
+
+            const rect = el.getBoundingClientRect();
+            return {
+                found: true,
+                tagName: el.tagName,
+                text: (el.innerText || el.textContent || "").trim().slice(0, 200),
+                value: "value" in el ? el.value : null,
+                visible: isVisible(el),
+                enabled: isEnabled(el),
+                rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+                attributes: {
+                    id: el.id || null,
+                    class: el.className?.toString?.() || null,
+                    placeholder: el.getAttribute("placeholder"),
+                    "aria-label": el.getAttribute("aria-label"),
+                    "aria-checked": el.getAttribute("aria-checked"),
+                    title: el.getAttribute("title"),
+                },
+            };
+        }, selector);
+    }
+
+    return {
+        async toBeVisible(opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                return s.found && s.visible ? s : null;
+            }, { ...opts, message: `expect ${selector} to be visible` });
+            return formatAssertResult(r, { assertion: "toBeVisible", selector });
+        },
+
+        async toBeHidden(opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                return !s.found || !s.visible ? s || { found: false } : null;
+            }, { ...opts, message: `expect ${selector} to be hidden` });
+            return formatAssertResult(r, { assertion: "toBeHidden", selector });
+        },
+
+        async toBeEnabled(opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                return s.found && s.enabled ? s : null;
+            }, { ...opts, message: `expect ${selector} to be enabled` });
+            return formatAssertResult(r, { assertion: "toBeEnabled", selector });
+        },
+
+        async toHaveText(expected, opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                if (!s.found) return null;
+                return s.text.includes(expected) ? s : null;
+            }, { ...opts, message: `expect ${selector} to have text "${expected}"` });
+            return formatAssertResult(r, { assertion: "toHaveText", selector, expected });
+        },
+
+        async toHaveValue(expected, opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                if (!s.found || s.value == null) return null;
+                return s.value === expected || s.value.includes?.(expected) ? s : null;
+            }, { ...opts, message: `expect ${selector} to have value "${expected}"` });
+            return formatAssertResult(r, { assertion: "toHaveValue", selector, expected });
+        },
+
+        async toHaveCount(expected, opts = {}) {
+            const r = await poll(async () => {
+                const count = await frame.evaluate((s) => {
+                    try { return document.querySelectorAll(s.startsWith("~") ? `[class*="${s.slice(1).replace(/^\./, "")}"]` : s).length; }
+                    catch { return -1; }
+                }, selector);
+                return count === expected ? count : null;
+            }, { ...opts, message: `expect ${selector} to have count ${expected}` });
+            return formatAssertResult(r, { assertion: "toHaveCount", selector, expected });
+        },
+
+        async toHaveAttribute(name, value, opts = {}) {
+            const r = await poll(async () => {
+                const s = await probe();
+                if (!s.found) return null;
+                const actual = s.attributes[name];
+                if (value === undefined) return actual != null ? actual : null;
+                return actual === value || actual?.includes?.(value) ? actual : null;
+            }, { ...opts, message: `expect ${selector} attribute ${name} to be "${value}"` });
+            return formatAssertResult(r, { assertion: "toHaveAttribute", selector, name, expected: value });
+        },
+    };
+}
+
+/**
+ * 表单校验断言：检查 frame 内是否还有 form-item-explain-error
+ */
+export function validation(frame) {
+    return {
+        async toPass(opts = {}) {
+            const r = await poll(async () => {
+                const errors = await frame.evaluate(() => {
+                    const items = Array.from(document.querySelectorAll(".ant-form-item-explain-error, .ant-form-item-has-error .ant-form-item-explain"));
+                    return items
+                        .filter((el) => {
+                            const rect = el.getBoundingClientRect();
+                            return rect.width > 0 && rect.height > 0;
+                        })
+                        .map((el) => {
+                            const formItem = el.closest(".ant-form-item");
+                            const label = formItem?.querySelector(".ant-form-item-label label, .ant-form-item-label")?.innerText?.trim() || "";
+                            return {
+                                field: label,
+                                message: (el.innerText || el.textContent || "").trim(),
+                            };
+                        });
+                });
+                return errors.length === 0 ? { errors: [] } : null;
+            }, { ...opts, message: "expect form validation to pass" });
+
+            if (r.passed) {
+                return formatAssertResult(r, { assertion: "validation.toPass", expected: "no errors" });
+            }
+            // 失败时把当前错误列表带回去
+            const currentErrors = await frame.evaluate(() => {
+                const items = Array.from(document.querySelectorAll(".ant-form-item-explain-error, .ant-form-item-has-error .ant-form-item-explain"));
+                return items.map((el) => {
+                    const formItem = el.closest(".ant-form-item");
+                    const label = formItem?.querySelector(".ant-form-item-label label, .ant-form-item-label")?.innerText?.trim() || "";
+                    return { field: label, message: (el.innerText || el.textContent || "").trim() };
+                });
+            }).catch(() => []);
+
+            return formatAssertResult(r, {
+                assertion: "validation.toPass",
+                expected: "no errors",
+                actual: currentErrors,
+            });
+        },
+
+        async toHaveError(fieldOrMessage, opts = {}) {
+            const r = await poll(async () => {
+                const errors = await frame.evaluate(() => {
+                    const items = Array.from(document.querySelectorAll(".ant-form-item-explain-error"));
+                    return items.map((el) => {
+                        const formItem = el.closest(".ant-form-item");
+                        const label = formItem?.querySelector(".ant-form-item-label label, .ant-form-item-label")?.innerText?.trim() || "";
+                        return { field: label, message: (el.innerText || el.textContent || "").trim() };
+                    });
+                });
+                const matched = errors.find((e) =>
+                    e.field.includes(fieldOrMessage) || e.message.includes(fieldOrMessage)
+                );
+                return matched || null;
+            }, { ...opts, message: `expect validation error for "${fieldOrMessage}"` });
+            return formatAssertResult(r, { assertion: "validation.toHaveError", expected: fieldOrMessage });
+        },
+    };
+}
+
+/**
+ * URL 断言（针对 page，不需要 poll，因为 url 通常已稳定，但提供选项化轮询）
+ */
+export function url(page) {
+    return {
+        async toContain(expected, opts = {}) {
+            const r = await poll(async () => {
+                const u = page.url();
+                return u.includes(expected) ? u : null;
+            }, { timeout: opts.timeout ?? 1000, interval: 100, message: `expect url to contain "${expected}"` });
+            return formatAssertResult(r, { assertion: "url.toContain", expected, actual: page.url() });
+        },
+
+        async toMatch(regex, opts = {}) {
+            const re = regex instanceof RegExp ? regex : new RegExp(regex);
+            const r = await poll(async () => {
+                const u = page.url();
+                return re.test(u) ? u : null;
+            }, { timeout: opts.timeout ?? 1000, interval: 100 });
+            return formatAssertResult(r, { assertion: "url.toMatch", expected: re.toString(), actual: page.url() });
+        },
+    };
+}
+
+/**
+ * API 捕获结果断言（基于 captureApi 的返回值）
+ * @param {object} captureResult - captureApi 返回对象
+ * @param {object} [options] - { scope: "current-frame"|"all", frameUrlContains }
+ */
+export function api(captureResult, options = {}) {
+    const allRequests = captureResult?.requests || [];
+    const scope = options.scope || "all";
+
+    // 按 frame 范围过滤请求
+    let requests = allRequests;
+    if (scope === "current-frame" && options.frameUrlContains) {
+        requests = allRequests.filter((r) => r.frameUrl && r.frameUrl.includes(options.frameUrlContains));
+    }
+
+    return {
+        toAllPass() {
+            const failed = requests.filter((r) => (r.status && r.status >= 400) || r.errorText);
+            const passed = failed.length === 0;
+            return {
+                passed,
+                assertion: "api.toAllPass",
+                expected: "all requests status < 400",
+                actual: failed.length === 0 ? "all ok" : failed,
+                totalRequests: allRequests.length,
+                scopedRequests: requests.length,
+                reason: passed ? null : `${failed.length}/${requests.length} requests failed`,
+            };
+        },
+
+        toHaveNoFailed() {
+            return this.toAllPass();
+        },
+
+        toInclude(urlPattern) {
+            const re = typeof urlPattern === "string" ? new RegExp(urlPattern) : urlPattern;
+            const matched = requests.find((r) => re.test(r.url));
+            return {
+                passed: Boolean(matched),
+                assertion: "api.toInclude",
+                expected: urlPattern.toString(),
+                actual: matched || null,
+                totalRequests: allRequests.length,
+                scopedRequests: requests.length,
+                reason: matched ? null : `no request matched ${urlPattern}`,
+            };
+        },
+
+        toHaveCount(expected) {
+            return {
+                passed: requests.length === expected,
+                assertion: "api.toHaveCount",
+                expected,
+                actual: requests.length,
+                totalRequests: allRequests.length,
+                scopedRequests: requests.length,
+                reason: requests.length === expected ? null : `got ${requests.length} requests`,
+            };
+        },
+    };
+}
+
+function formatAssertResult(pollResult, meta) {
+    return {
+        passed: pollResult.passed,
+        assertion: meta.assertion,
+        selector: meta.selector,
+        expected: meta.expected,
+        actual: meta.actual ?? pollResult.value,
+        attempts: pollResult.attempts,
+        duration: pollResult.duration,
+        reason: pollResult.passed ? null : pollResult.reason,
+    };
+}
+
+/**
+ * 工厂：返回绑定 frame/page 的 expect 接口
+ */
+export function createExpect(target) {
+    return {
+        poll,
+        locator: (selector) => locator(target.frame || target, selector),
+        validation: () => validation(target.frame || target),
+        url: () => url(target.page || target),
+        api,
+    };
+}
+
+export default { poll, locator, validation, url, api, createExpect };

package/standard-skill/local-browser-test/lib/shared-deps.js

@@ -0,0 +1,137 @@
+/**
+ * 共享依赖加载器
+ *
+ * 浏览器自动化依赖安装到 ~/.szcd-mcp/deps/node_modules/，所有项目共享复用。
+ * 主链路 observe/act/assert 只安装 puppeteer-core；视觉对比按需安装 pixelmatch/pngjs/sharp。
+ */
+
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+/** 共享缓存目录 */
+const SHARED_DEPS_DIR = path.join(homedir(), ".szcd-mcp", "deps");
+
+/** 核心浏览器自动化依赖 */
+const CORE_PACKAGES = ["puppeteer-core"];
+
+/** 视觉对比依赖 */
+const VISUAL_COMPARE_PACKAGES = ["pixelmatch", "pngjs", "sharp"];
+
+/** 兼容旧导出 */
+const PACKAGES = [...CORE_PACKAGES, ...VISUAL_COMPARE_PACKAGES];
+
+/**
+ * 从共享缓存目录加载模块
+ * @param {string} moduleName - 模块名
+ * @returns {*} 模块导出
+ */
+export function loadFromShared(moduleName) {
+    const require_ = createRequire(path.join(SHARED_DEPS_DIR, "node_modules", "_"));
+    return require_(moduleName);
+}
+
+function ensurePackageJson() {
+    fs.mkdirSync(SHARED_DEPS_DIR, { recursive: true });
+
+    const pkgPath = path.join(SHARED_DEPS_DIR, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+        fs.writeFileSync(pkgPath, JSON.stringify({
+            name: "szcd-mcp-shared-deps",
+            version: "1.0.0",
+            private: true,
+        }, null, 2));
+    }
+}
+
+function isPackageInstalled(packageName) {
+    try {
+        const require_ = createRequire(path.join(SHARED_DEPS_DIR, "node_modules", "_"));
+        require_.resolve(packageName);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function installPackages(packages, label) {
+    const missing = packages.filter((packageName) => !isPackageInstalled(packageName));
+    if (missing.length === 0) return;
+
+    process.stderr.write(`[shared-deps] 正在安装${label}: ${missing.join(" ")}\n`);
+    process.stderr.write(`[shared-deps] 安装目录: ${SHARED_DEPS_DIR}\n`);
+
+    ensurePackageJson();
+
+    const { execSync } = await import("node:child_process");
+    const pkgList = missing.join(" ");
+    const registryFlags = [
+        "--registry=https://registry.npmmirror.com",
+        "--@img:registry=https://registry.npmmirror.com",
+    ];
+    const speedFlags = [
+        "--prefer-offline",
+        "--no-audit",
+        "--no-fund",
+        "--omit=dev",
+        "--package-lock=false",
+        "--loglevel=warn",
+    ];
+    const sharpFlags = missing.includes("sharp") ? [
+        "--sharp_binary_host=https://npmmirror.com/mirrors/sharp",
+        "--sharp_libvips_binary_host=https://npmmirror.com/mirrors/sharp-libvips",
+    ] : [];
+    const installFlags = [...registryFlags, ...speedFlags, ...sharpFlags].join(" ");
+
+    try {
+        execSync(`npm install ${installFlags} ${pkgList}`.trim(), {
+            cwd: SHARED_DEPS_DIR,
+            stdio: "inherit",
+            timeout: 180000,
+        });
+    } catch (err) {
+        throw new Error(
+            `${label}安装失败。请手动执行：\n` +
+            `  cd ${SHARED_DEPS_DIR} && npm install ${installFlags} ${pkgList}\n` +
+            `原始错误：${err.message}`
+        );
+    }
+
+    process.stderr.write(`[shared-deps] ${label}安装完成。\n`);
+}
+
+export async function ensureCoreDeps() {
+    await installPackages(CORE_PACKAGES, "浏览器核心依赖");
+}
+
+export async function ensureVisualCompareDeps() {
+    await ensureCoreDeps();
+    await installPackages(VISUAL_COMPARE_PACKAGES, "视觉对比依赖");
+}
+
+/**
+ * 确保全部共享依赖已安装，保留给旧调用兼容。
+ * @returns {Promise<void>}
+ */
+export async function ensureSharedDeps() {
+    await ensureVisualCompareDeps();
+}
+
+/**
+ * 检查核心依赖是否已安装
+ * @returns {boolean}
+ */
+export function isCoreDepsInstalled() {
+    return CORE_PACKAGES.every(isPackageInstalled);
+}
+
+/**
+ * 检查全部共享依赖是否已安装
+ * @returns {boolean}
+ */
+export function isSharedDepsInstalled() {
+    return PACKAGES.every(isPackageInstalled);
+}
+
+export { SHARED_DEPS_DIR, PACKAGES, CORE_PACKAGES, VISUAL_COMPARE_PACKAGES };