@szc-ft/mcp-szcd-client 0.34.2 → 0.38.0

package/qwen-extension/skills/local-browser-test/lib/retry-policy.js

@@ -0,0 +1,160 @@
+/**
+ * 统一重试策略（PR #6 v3）
+ *
+ * 三层重试：
+ *   1. 步骤级 retries（验证码过期等场景，默认 2 次）
+ *   2. 用例级 retries（CI 抖动，--retries 参数，默认 0，CI 模式 2 次）
+ *   3. flaky 检测（5 次中 1 挂 4 过 → 标 flaky，仍算 PASS）
+ *
+ * 写操作禁重试白名单（act.click 文本匹配 + apiCall POST 默认）：
+ *   - 删除 / 提交 / 发布 / 上线 / 注销
+ *   - delete / submit / publish / deploy / logout
+ *   - apiCall POST 默认禁重试（避免重复写操作）
+ */
+
+const NO_RETRY_KEYWORDS_ZH = ['删除', '提交', '发布', '上线', '注销'];
+const NO_RETRY_KEYWORDS_EN = ['delete', 'submit', 'publish', 'deploy', 'logout'];
+const NO_RETRY_TYPES = ['apiCall'];  // apiCall 默认禁重试（除非显式 noRetry: false）
+
+const DEFAULT_OPTIONS = {
+  maxRetries: 0,           // 用例级 retries
+  maxRetriesPerStep: 2,    // 步骤级 retries
+  flakyThreshold: 5,       // flaky 检测：5 次中 1 挂 4 过
+  flakyPass: 4,            // flaky 必须 ≥ 4 挂 1
+  noRetryActions: true,    // 全局写操作禁重试
+};
+
+export class RetryPolicy {
+    constructor(options = {}) {
+        this.maxRetries = options.maxRetries ?? DEFAULT_OPTIONS.maxRetries;
+        this.maxRetriesPerStep = options.maxRetriesPerStep ?? DEFAULT_OPTIONS.maxRetriesPerStep;
+        this.flakyThreshold = options.flakyThreshold ?? DEFAULT_OPTIONS.flakyThreshold;
+        this.flakyPass = options.flakyPass ?? DEFAULT_OPTIONS.flakyPass;
+        this.noRetryActions = options.noRetryActions ?? DEFAULT_OPTIONS.noRetryActions;
+    }
+
+    /**
+     * 判断某 step 是否允许重试
+     * @param {object} step
+     * @returns {boolean}
+     */
+    isStepRetryable(step) {
+        // 1. step 显式 noRetry 优先级最高
+        if (step.noRetry === true) return false;
+        if (step.noRetry === false) return true;
+
+        // 2. 全局写操作禁重试
+        if (this.noRetryActions) {
+            // act 步骤：检查文本含危险关键词
+            if (step.type === 'act' && step.click) {
+                const text = String(step.click).toLowerCase();
+                if (NO_RETRY_KEYWORDS_ZH.some((k) => text.includes(k.toLowerCase())) ||
+                    NO_RETRY_KEYWORDS_EN.some((k) => text.includes(k))) {
+                    return false;
+                }
+            }
+            // apiCall 步骤：写方法（POST/PUT/DELETE/PATCH）默认禁重试
+            // 读方法（GET/HEAD/OPTIONS）允许重试
+            if (NO_RETRY_TYPES.includes(step.type)) {
+                const method = String(step.method ?? '').toUpperCase();
+                if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+
+    /**
+     * 步骤级重试：执行 fn 直到成功或达到 maxRetries
+     * @param {object} step
+     * @param {() => Promise<object>} fn - 实际执行的函数，返回 { passed: bool, ... }
+     * @returns {Promise<{result: object, retryCount: number, aborted: boolean}>}
+     */
+    async withStepRetry(step, fn) {
+        if (!this.isStepRetryable(step)) {
+            return { result: await fn(), retryCount: 0, aborted: false };
+        }
+        let lastResult;
+        for (let i = 0; i <= this.maxRetriesPerStep; i++) {
+            lastResult = await fn();
+            if (lastResult.passed !== false) {
+                return { result: lastResult, retryCount: i, aborted: false };
+            }
+            // 失败
+        }
+        return { result: lastResult, retryCount: this.maxRetriesPerStep, aborted: true };
+    }
+
+    /**
+     * 用例级重试：执行 fn 直到成功或达到 maxRetries
+     * @param {string} caseName
+     * @param {() => Promise<{passed: boolean, ...}>} fn
+     * @returns {Promise<{result: object, history: object[], retryCount: number, flaky: boolean}>}
+     */
+    async withCaseRetry(caseName, fn) {
+        const history = [];
+        let lastResult;
+        for (let i = 0; i <= this.maxRetries; i++) {
+            lastResult = await fn();
+            history.push({ run: i + 1, passed: lastResult.passed ?? false });
+            if (lastResult.passed !== false) {
+                if (i > 0) {
+                    console.log(`  ✓ case retry ${i} succeeded: ${caseName}`);
+                }
+                return {
+                    result: lastResult,
+                    history,
+                    retryCount: i,
+                    flaky: this.detectFlaky(history)
+                };
+            }
+        }
+        return {
+            result: lastResult,
+            history,
+            retryCount: this.maxRetries,
+            flaky: this.detectFlaky(history)
+        };
+    }
+
+    /**
+     * flaky 检测：5 次中 1 挂 4 过 → 标 flaky
+     * @param {Array<{run: number, passed: boolean}>} history
+     * @returns {boolean}
+     */
+    detectFlaky(history) {
+        if (history.length < this.flakyThreshold) return false;
+        const passed = history.filter((h) => h.passed).length;
+        const failed = history.length - passed;
+        return failed === this.flakyThreshold - this.flakyPass && passed === this.flakyPass;
+    }
+
+    /**
+     * 计算 summary.fidelity（基于 retries / passed / total 算可信度）
+     * @param {object} stats
+     * @returns {number} 0-1 之间的可信度分数
+     */
+    computeFidelity(stats) {
+        if (stats.total === 0) return 1.0;
+        const base = stats.passed / stats.total;
+        const retryPenalty = Math.min((stats.retryCount ?? 0) * 0.1, 0.3);
+        const flakyPenalty = (stats.flaky ?? 0) * 0.05;
+        return Math.round((Math.max(0, base - retryPenalty - flakyPenalty)) * 100) / 100;
+    }
+}
+
+/**
+ * 工厂函数：从 plan.recovery 构造 RetryPolicy
+ * @param {object} planRecovery - plan.recovery 字段
+ * @returns {RetryPolicy}
+ */
+export function retryPolicyFromPlan(planRecovery = {}) {
+    return new RetryPolicy({
+        maxRetries: planRecovery.maxRetries ?? 0,
+        maxRetriesPerStep: planRecovery.maxRetriesPerStep ?? 2,
+        flakyThreshold: planRecovery.flakyThreshold ?? 5,
+        flakyPass: planRecovery.flakyPass ?? 4,
+        noRetryActions: planRecovery.noRetryActions ?? true
+    });
+}

package/qwen-extension/skills/local-browser-test/lib/storage-state.js

@@ -0,0 +1,111 @@
+/**
+ * storageState: puppeteer cookies ↔ Playwright 兼容格式
+ *
+ * Playwright storageState 格式：
+ *   { cookies: [...], origins: [{ origin, localStorage: [{name, value}] }] }
+ *
+ * 用于：
+ *   - 跨测试复用登录态（不重复登录）
+ *   - 接管浏览器模式（globalSetupTakeover）
+ *   - 自动填表模式（globalSetupFillForm）
+ */
+
+import fs from "node:fs";
+
+/**
+ * 从当前 browser context 抓取 cookies + localStorage
+ * @param {import('puppeteer').Page} page
+ * @returns {Promise<{cookies: Array, origins: Array}>}
+ */
+export async function captureStorageState(page) {
+  const context = page.browserContext();
+  const cookies = await context.cookies();
+  const origins = await extractLocalStorage(context);
+
+  return { cookies, origins };
+}
+
+async function extractLocalStorage(context) {
+  const pages = await context.pages();
+  const originMap = new Map();
+
+  for (const p of pages) {
+    try {
+      const url = new URL(p.url());
+      const origin = url.origin;
+      const ls = await p.evaluate(() => {
+        const result = [];
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          result.push({ name: key, value: localStorage.getItem(key) });
+        }
+        return result;
+      });
+      if (ls.length > 0) {
+        if (!originMap.has(origin)) originMap.set(origin, []);
+        originMap.get(origin).push(...ls);
+      }
+    } catch (e) {
+      // 跨域 iframe / about:blank 等忽略
+    }
+  }
+
+  return Array.from(originMap.entries()).map(([origin, localStorage]) => ({
+    origin,
+    localStorage
+  }));
+}
+
+/**
+ * 加载 storageState 并应用到 browser context
+ * @param {import('puppeteer').BrowserContext} context
+ * @param {string} filePath
+ */
+export async function applyStorageState(context, filePath) {
+  if (!fs.existsSync(filePath)) {
+    console.warn(`⚠️  storageState 不存在: ${filePath}，跳过`);
+    return;
+  }
+
+  const state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+
+  // 1. 注入 cookies
+  if (state.cookies?.length) {
+    await context.setCookie(...state.cookies);
+  }
+
+  // 2. 注入 localStorage（需要在目标 origin 的 page 内执行）
+  if (state.origins?.length) {
+    for (const { origin, localStorage } of state.origins) {
+      if (!localStorage?.length) continue;
+      const page = await context.newPage();
+      try {
+        await page.goto(origin, { waitUntil: "domcontentloaded", timeout: 10000 });
+        await page.evaluate((items) => {
+          for (const { name, value } of items) {
+            localStorage.setItem(name, value);
+          }
+        }, localStorage);
+      } catch (e) {
+        console.warn(`⚠️  无法访问 ${origin} 注入 localStorage: ${e.message}`);
+      }
+      await page.close();
+    }
+  }
+}
+
+/**
+ * 从 storageState 提取 Cookie 头字符串（供 axios request 共享使用）
+ * @param {string} filePath
+ * @param {string} [targetOrigin] 可选，只取该 origin 的 cookies
+ * @returns {string} Cookie 头（空字符串如果文件不存在或无 cookies）
+ */
+export function buildCookieHeader(filePath, targetOrigin = null) {
+  if (!fs.existsSync(filePath)) return "";
+  const state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  const cookies = state.cookies ?? [];
+  return cookies
+    .filter((c) => !targetOrigin || c.domain.endsWith(targetOrigin.replace(/^https?:\/\//, "")))
+    .map((c) => `${c.name}=${c.value}`)
+    .join("; ");
+}

package/qwen-extension/skills/local-browser-test/lib/tag-runner.js

@@ -0,0 +1,103 @@
+/**
+ * 用例标签过滤（PR #7 v3）
+ *
+ * 标签格式：@smoke / @p0 / @p1 / @full / @flaky
+ * 匹配模式：any（默认，含任一）/ all（必须含全部）
+ * 应用层级：plan 顶层 + case 顶层
+ *
+ * 与 CI 集成：
+ *   - PR 冒烟：--tags @smoke
+ *   - 合并前：--tags "@p0,@p1" --tag-mode any
+ *   - 定时全量：--tags @full
+ *   - 排除 flaky：--tags @p0 --exclude-tags @flaky
+ */
+
+const TAG_PATTERN = /^@[\w-]+$/;
+
+/**
+ * 解析逗号分隔的 tag 字符串
+ * @param {string|undefined|null} input
+ * @returns {string[]}
+ */
+export function parseTags(input) {
+  if (!input) return [];
+  if (Array.isArray(input)) return input.filter(Boolean);
+  return String(input)
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+/**
+ * 判断 tags 数组是否匹配过滤条件
+ * @param {string[]} caseTags
+ * @param {string[]} filterTags
+ * @param {'any'|'all'} mode
+ * @returns {boolean}
+ */
+export function matchTags(caseTags, filterTags, mode = 'any') {
+  if (!filterTags || filterTags.length === 0) return true;  // 不过滤
+  if (!caseTags || caseTags.length === 0) return false;     // 没 tag 不匹配
+
+  if (mode === 'all') {
+    return filterTags.every((t) => caseTags.includes(t));
+  }
+  // mode === 'any'（默认）：含任一
+  return filterTags.some((t) => caseTags.includes(t));
+}
+
+/**
+ * 过滤 cases
+ * @param {Array} cases
+ * @param {object} options
+ * @returns {Array}
+ */
+export function filterCasesByTags(cases, options = {}) {
+  const {
+    tags = [],
+    excludeTags = [],
+    mode = 'any'
+  } = options;
+
+  return cases.filter((c) => {
+    const caseTags = c.tags ?? [];
+    // 排除优先：excludeTags 命中 → 跳过
+    if (excludeTags.length > 0 && matchTags(caseTags, excludeTags, 'any')) {
+      return false;
+    }
+    // tags 不过滤 → 全部通过
+    if (tags.length === 0) return true;
+    // tags 命中 → 通过
+    return matchTags(caseTags, tags, mode);
+  });
+}
+
+/**
+ * 过滤 plans（testCase 数组）
+ * @param {Array} plans
+ * @param {object} options
+ * @returns {Array}
+ */
+export function filterPlansByTags(plans, options = {}) {
+  const { tags = [], excludeTags = [], mode = 'any' } = options;
+  return plans.filter((p) => {
+    const planTags = p.tags ?? [];
+    if (excludeTags.length > 0 && matchTags(planTags, excludeTags, 'any')) {
+      return false;
+    }
+    if (tags.length > 0 && !matchTags(planTags, tags, mode)) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * 校验 tag 格式（@ 前缀 + 字母数字下划线连字符）
+ * @param {string[]} tags
+ * @returns {{valid: boolean, invalid: string[]}}
+ */
+export function validateTags(tags) {
+  const invalid = tags.filter((t) => !TAG_PATTERN.test(t));
+  return { valid: invalid.length === 0, invalid };
+}

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

@@ -18,6 +18,8 @@ export function compilePlan(plan) {
     return {
         title: plan.description || plan.planId || `auto-${Date.now()}`,
         labels: plan.labels || [],
+        // ★ PR #7 v3: plan 顶层支持 tags（@smoke / @p0 / @p1 / @full / @flaky）
+        tags: plan.tags || [],
         setup: {
             findPage: plan.findPage || undefined,
             findFrame: plan.findFrame || undefined,

package/qwen-extension/skills/local-browser-test/lib/trace-collector.js

@@ -0,0 +1,94 @@
+/**
+ * puppeteer trace 录制（PR #5）
+ *
+ * 用 CDP Tracing.start / Tracing.end 录制 trace。
+ * 输出 trace.zip（含 DOM snapshot + 网络 + console + 操作步骤）。
+ *
+ * 注意：puppeteer 自身不提供 zip 打包；这里输出 trace.json（CDP 原始格式）
+ *      + meta.json（标签 + 时间戳），前端 HTML 报告可读这两个文件。
+ *      真正的 zip 打包可由 reporter 阶段用 archiver 完成（PR #5 范围外）。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_CATEGORIES = 'devtools.timeline,disabled-by-default-devtools.timeline,blink.user_timing';
+
+export class TraceCollector {
+    /**
+     * @param {string} runDir - 落盘目录（runs/<id>/）
+     */
+    constructor(runDir) {
+        this.runDir = runDir;
+        this.collecting = false;
+        this.session = null;
+        this.events = [];
+    }
+
+    /**
+     * 启动 trace 录制
+     * @param {import('puppeteer').Page} page
+     */
+    async start(page) {
+        if (this.collecting) return;
+        try {
+            this.session = await page.target().createCDPSession();
+            await this.session.send('Tracing.start', {
+                categories: DEFAULT_CATEGORIES,
+                options: 'sampling-frequency=10000',
+                transferMode: 'ReportEvents'
+            });
+            this.collecting = true;
+        } catch (e) {
+            console.warn(`⚠️  TraceCollector.start 失败: ${e.message}`);
+        }
+    }
+
+    /**
+     * 停止 trace 录制，落盘
+     * @returns {Promise<string|null>} trace.json 路径
+     */
+    async stop() {
+        if (!this.collecting) return null;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                console.warn('⚠️  TraceCollector.stop 超时（5s）');
+                resolve(null);
+            }, 5000);
+
+            this.session.once('Tracing.dataCollected', (data) => {
+                clearTimeout(timer);
+                try {
+                    this.events.push(...(data.value ?? []));
+                } catch (e) {
+                    console.warn(`⚠️  收集 trace 事件失败: ${e.message}`);
+                }
+            });
+
+            this.session.send('Tracing.end').then(() => {
+                clearTimeout(timer);
+                // 给 dataCollected 1s 缓冲时间
+                setTimeout(() => {
+                    try {
+                        fs.mkdirSync(this.runDir, { recursive: true });
+                        const tracePath = path.join(this.runDir, 'trace.json');
+                        fs.writeFileSync(tracePath, JSON.stringify({
+                            schemaVersion: 1,
+                            capturedAt: new Date().toISOString(),
+                            events: this.events
+                        }, null, 2));
+                        this.collecting = false;
+                        resolve(tracePath);
+                    } catch (e) {
+                        console.warn(`⚠️  TraceCollector 落盘失败: ${e.message}`);
+                        resolve(null);
+                    }
+                }, 1000);
+            }).catch((e) => {
+                clearTimeout(timer);
+                console.warn(`⚠️  Tracing.end 失败: ${e.message}`);
+                resolve(null);
+            });
+        });
+    }
+}

package/qwen-extension/skills/local-browser-test/lib/trend-aggregator.js

@@ -0,0 +1,97 @@
+/**
+ * trend.json 按日聚合（v4 关键能力）
+ *
+ * 设计：
+ *   - schemaVersion: 1
+ *   - byDay[YYYY-MM-DD]: { runs, total, passed, failed, flaky, skipped,
+ *                          byStrategy: {api, ui, newman, browser},
+ *                          byTag: {}, byProject: {}, byBranch: {} }
+ */
+
+import fs from "node:fs";
+
+const DEFAULTS = {
+  schemaVersion: 1,
+  updatedAt: null,
+  byDay: {}
+};
+
+/**
+ * 把一次 run 追加到 trend.json
+ * @param {object} result
+ * @param {string} trendPath
+ */
+export function appendToTrend(result, trendPath) {
+  const trend = fs.existsSync(trendPath)
+    ? JSON.parse(fs.readFileSync(trendPath, "utf8"))
+    : structuredClone(DEFAULTS);
+
+  const day = (result.startedAt ?? new Date().toISOString()).slice(0, 10);
+  if (!trend.byDay[day]) {
+    trend.byDay[day] = {
+      runs: 0, total: 0, passed: 0, failed: 0, flaky: 0, skipped: 0,
+      byStrategy: { api: 0, ui: 0, newman: 0, browser: 0 },
+      byTag: {},
+      byProject: {},
+      byBranch: {}
+    };
+  }
+
+  const d = trend.byDay[day];
+  d.runs += 1;
+  d.total += result.stats?.total ?? 0;
+  d.passed += result.stats?.passed ?? 0;
+  d.failed += result.stats?.failed ?? 0;
+  d.flaky += result.stats?.flaky ?? 0;
+  d.skipped += result.stats?.skipped ?? 0;
+
+  // ★ v4 新增：按 strategy 分桶
+  const strategy = result.strategy ?? "newman";
+  d.byStrategy[strategy] = (d.byStrategy[strategy] ?? 0) + (result.stats?.total ?? 0);
+
+  // 按 tag 分桶
+  if (result.tag) {
+    if (!d.byTag[result.tag]) d.byTag[result.tag] = { runs: 0, passed: 0, failed: 0 };
+    const t = d.byTag[result.tag];
+    t.runs += 1;
+    t.passed += result.stats?.passed ?? 0;
+    t.failed += result.stats?.failed ?? 0;
+  }
+
+  // 按 project 分桶
+  if (result.project) {
+    if (!d.byProject[result.project]) d.byProject[result.project] = { runs: 0, passed: 0, failed: 0 };
+    const p = d.byProject[result.project];
+    p.runs += 1;
+    p.passed += result.stats?.passed ?? 0;
+    p.failed += result.stats?.failed ?? 0;
+  }
+
+  // 按 branch 分桶
+  if (result.branch) {
+    if (!d.byBranch[result.branch]) d.byBranch[result.branch] = { runs: 0, passed: 0, failed: 0 };
+    const b = d.byBranch[result.branch];
+    b.runs += 1;
+    b.passed += result.stats?.passed ?? 0;
+    b.failed += result.stats?.failed ?? 0;
+  }
+
+  trend.updatedAt = new Date().toISOString();
+  fs.writeFileSync(trendPath, JSON.stringify(trend, null, 2));
+}
+
+/**
+ * 裁剪 trend.json：保留最近 N 天
+ * @param {string} trendPath
+ * @param {number} days
+ */
+export function trimTrendToDays(trendPath, days) {
+  if (!fs.existsSync(trendPath)) return;
+  const trend = JSON.parse(fs.readFileSync(trendPath, "utf8"));
+  const cutoff = new Date(Date.now() - days * 24 * 3600 * 1000).toISOString().slice(0, 10);
+  for (const day of Object.keys(trend.byDay)) {
+    if (day < cutoff) delete trend.byDay[day];
+  }
+  trend.updatedAt = new Date().toISOString();
+  fs.writeFileSync(trendPath, JSON.stringify(trend, null, 2));
+}