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

package/opencode-extension/skills/local-browser-test/lib/test-plan.js

@@ -0,0 +1,48 @@
+/**
+ * plan → testCase 兼容编译器
+ *
+ * 把现有线性 plan JSON 自动升级为 testCase 对象，无需用户迁移。
+ * 规则：
+ *   - plan.steps[] → testCase.steps
+ *   - plan.dataset 存在 → 参数化执行
+ *   - 新 step type（antSelect/antInput/expect/formFill 等）原样保留
+ *   - 旧 step type（click/type/checkElement 等）也原样保留
+ */
+
+/**
+ * 编译 plan JSON 为 testCase 对象
+ * @param {object} plan - 现有 plan 格式
+ * @returns {object} testCase 对象
+ */
+export function compilePlan(plan) {
+    return {
+        title: plan.description || plan.planId || `auto-${Date.now()}`,
+        labels: plan.labels || [],
+        setup: {
+            findPage: plan.findPage || undefined,
+            findFrame: plan.findFrame || undefined,
+            apiCapture: plan.apiCapture || undefined,
+        },
+        dataset: plan.dataset || [],
+        steps: plan.steps || [],
+        recovery: plan.recovery || {},
+        teardown: plan.teardown || undefined,
+        // 透传元数据，报告使用
+        _planId: plan.planId,
+        _options: plan.options,
+    };
+}
+
+/**
+ * 编译 plan 文件内容为 testCase 对象数组
+ * @param {object|object[]} fileContent - plan JSON 或 plan 数组
+ * @returns {object[]} testCase 数组
+ */
+export function compilePlanFile(fileContent) {
+    if (Array.isArray(fileContent)) {
+        return fileContent.map(compilePlan);
+    }
+    return [compilePlan(fileContent)];
+}
+
+export default { compilePlan, compilePlanFile };

package/opencode-extension/skills/local-browser-test/lib/visual-compare.js

@@ -0,0 +1,192 @@
+/**
+ * 视觉对比引擎 - pixelmatch + sharp
+ *
+ * 功能：
+ * - 全局像素对比，输出还原度评分
+ * - 分区域对比（按 CSS selector 裁剪后分别评分）
+ * - 三色 diff 图输出（红=真实差异，黄=抗锯齿，蓝=轻微色差）
+ * - 自动 resize 设计稿到截图尺寸
+ *
+ * 依赖从共享缓存加载（~/.szcd-mcp/deps/）：
+ * - sharp: 图片处理和 resize
+ * - pixelmatch: 像素对比
+ * - pngjs: PNG 编解码
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ensureVisualCompareDeps, loadFromShared } from "./shared-deps.js";
+
+/**
+ * 全局视觉对比
+ * @param {string} screenshotPath - 截图文件路径
+ * @param {string} designImagePath - 设计稿图片路径
+ * @param {object} options
+ * @param {number} [options.threshold=0.1] - 颜色差异阈值 (0-1)
+ * @param {string} [options.outputDir] - diff 图输出目录
+ * @returns {Promise<object>} 对比结果
+ */
+export async function compareDesign(screenshotPath, designImagePath, options = {}) {
+    // 视觉对比才安装 pixelmatch/pngjs/sharp，避免 observe 主链路被重依赖阻塞
+    await ensureVisualCompareDeps();
+    const sharp = loadFromShared("sharp");
+    const pixelmatch = loadFromShared("pixelmatch");
+    const { PNG } = loadFromShared("pngjs");
+
+    // 1. 读取图片元数据
+    const screenshotMeta = await sharp(screenshotPath).metadata();
+    const screenshotBuf = await sharp(screenshotPath).png().toBuffer();
+    const designBuf = await sharp(designImagePath).png().toBuffer();
+
+    // 2. 以截图尺寸为基准 resize 设计稿
+    const { width, height } = screenshotMeta;
+    const designResized = await sharp(designBuf)
+        .resize(width, height, { fit: "fill" })
+        .png()
+        .toBuffer();
+
+    // 3. 解码为像素数据
+    const img1 = PNG.sync.read(screenshotBuf);
+    const img2 = PNG.sync.read(designResized);
+    const diff = new PNG({ width, height });
+
+    // 4. pixelmatch 对比
+    const threshold = options.threshold ?? 0.1;
+    const diffPixels = pixelmatch(img1.data, img2.data, diff.data, width, height, {
+        threshold,
+        includeAA: false,
+        alpha: 0.1,
+        aaColor: [255, 255, 0],        // 黄色 = 抗锯齿差异
+        diffColor: [255, 0, 0],          // 红色 = 真实差异
+        diffColorAlt: [0, 100, 255],     // 蓝色 = 轻微色差（低于阈值）
+    });
+
+    const totalPixels = width * height;
+    const fidelity = parseFloat(((totalPixels - diffPixels) / totalPixels * 100).toFixed(2));
+
+    // 5. 保存 diff 图
+    let diffImagePath = null;
+    if (options.outputDir) {
+        if (!fs.existsSync(options.outputDir)) {
+            fs.mkdirSync(options.outputDir, { recursive: true });
+        }
+        diffImagePath = path.join(options.outputDir, `diff-global-${Date.now()}.png`);
+        fs.writeFileSync(diffImagePath, PNG.sync.write(diff));
+    }
+
+    // 6. 区域对比（如果有）
+    const regions = [];
+    if (options.regions?.length && options.page) {
+        for (const region of options.regions) {
+            try {
+                const regionResult = await compareRegion(
+                    screenshotPath, designImagePath, region, { ...options, sharp, PNG, pixelmatch }
+                );
+                regions.push(regionResult);
+            } catch (err) {
+                regions.push({
+                    name: region.name,
+                    selector: region.selector,
+                    error: err.message,
+                    fidelity: null,
+                });
+            }
+        }
+    }
+
+    return {
+        fidelity,
+        diffPixels,
+        totalPixels,
+        width,
+        height,
+        diffImagePath,
+        regions,
+    };
+}
+
+/**
+ * 区域对比 - 通过 Puppeteer 获取元素位置后裁剪对比
+ * @param {string} screenshotPath
+ * @param {string} designImagePath
+ * @param {object} region - { name, selector }
+ * @param {object} deps - { sharp, PNG, pixelmatch, page, outputDir, threshold }
+ * @returns {Promise<object>}
+ */
+async function compareRegion(screenshotPath, designImagePath, region, deps) {
+    const { sharp, PNG, pixelmatch, page, outputDir } = deps;
+    const threshold = deps.threshold ?? 0.1;
+
+    // 获取元素边界框
+    const boundingBox = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        return {
+            x: Math.round(rect.x),
+            y: Math.round(rect.y),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+        };
+    }, region.selector);
+
+    if (!boundingBox) {
+        return {
+            name: region.name,
+            selector: region.selector,
+            error: `Element not found: ${region.selector}`,
+            fidelity: null,
+        };
+    }
+
+    // 用 sharp 裁剪两张图的对应区域
+    const screenshotRegion = await sharp(screenshotPath)
+        .extract(boundingBox)
+        .png()
+        .toBuffer();
+
+    const designRegion = await sharp(designImagePath)
+        .resize(boundingBox.width, boundingBox.height, { fit: "fill" })
+        .extract({
+            left: 0,
+            top: 0,
+            width: boundingBox.width,
+            height: boundingBox.height,
+        })
+        .png()
+        .toBuffer();
+
+    // 像素对比
+    const img1 = PNG.sync.read(screenshotRegion);
+    const img2 = PNG.sync.read(designRegion);
+    const diff = new PNG({ width: img1.width, height: img1.height });
+
+    const diffPixels = pixelmatch(img1.data, img2.data, diff.data, img1.width, img1.height, {
+        threshold,
+        includeAA: false,
+        alpha: 0.1,
+    });
+
+    const totalPixels = img1.width * img1.height;
+    const fidelity = parseFloat(((totalPixels - diffPixels) / totalPixels * 100).toFixed(2));
+
+    // 保存区域 diff 图
+    let diffImagePath = null;
+    if (outputDir) {
+        const safeName = region.name.replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, "_");
+        diffImagePath = path.join(outputDir, `diff-region-${safeName}-${Date.now()}.png`);
+        fs.writeFileSync(diffImagePath, PNG.sync.write(diff));
+    }
+
+    return {
+        name: region.name,
+        selector: region.selector,
+        boundingBox,
+        fidelity,
+        diffPixels,
+        totalPixels,
+        diffImagePath,
+    };
+}
+
+export default { compareDesign };