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

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

@@ -0,0 +1,94 @@
+/**
+ * 通用脱敏函数。所有落盘 JSON 必走。
+ *
+ * 覆盖字段：password / verifyCode / credentials / token / apiKey / cookie 等
+ * 覆盖字符串：URL query 参数、Authorization header value、JSON 字段值
+ *
+ * 完整覆盖范围见 REDACT_KEYS / REDACT_PATTERNS
+ */
+
+const REDACT_KEYS = [
+  'password', 'verifyCode', 'credentials', 'auth',
+  'token', 'accessToken', 'refreshToken', 'apiKey',
+  'authorization', 'cookie', 'set-cookie', 'x-auth', 'x-token', 'x-api-key',
+  'secret', 'privateKey', 'clientSecret'
+];
+
+const REDACT_PATTERNS = [
+  // URL query 参数：(?token=abc | &password=xxx | ?code=6)
+  /([?&])(token|password|verifyCode|code|apiKey|secret)=([^&\s]+)/g,
+  // Authorization header value
+  /(Bearer\s+)[A-Za-z0-9\-._~+/]+=*/g,
+  // JSON 字段值
+  /"(token|password|verifyCode|apiKey|secret)"\s*:\s*"[^"]+"/g,
+];
+
+/**
+ * 递归脱敏对象
+ * @param {any} obj
+ * @returns {any} 新的脱敏后对象（深拷贝，不修改原对象）
+ */
+export function redact(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (Array.isArray(obj)) return obj.map(redact);
+  if (typeof obj !== 'object') return redactString(String(obj));
+  return Object.fromEntries(
+    Object.entries(obj).map(([k, v]) => {
+      if (REDACT_KEYS.some(r => k.toLowerCase().includes(r.toLowerCase()))) {
+        return [k, '***REDACTED***'];
+      }
+      return [k, redact(v)];
+    })
+  );
+}
+
+function redactString(str) {
+  let result = str;
+  for (const pat of REDACT_PATTERNS) {
+    result = result.replace(pat, (match, p1, p2, p3) => {
+      if (p1 === '?' || p1 === '&') return `${p1}${p2}=***`;
+      if (p1 === 'Bearer ') return `${p1}***`;
+      // JSON 字段值：把 value 部分替换为 "***"
+      return match.replace(/:\s*"[^"]+"/, ': "***"');
+    });
+  }
+  return result;
+}
+
+/**
+ * 脱敏 HTTP headers 数组 [{ key, value }]
+ * @param {Array<{key: string, value: string}>} headers
+ * @returns {Array<{key: string, value: string}>}
+ */
+export function redactHeaders(headers) {
+  if (!Array.isArray(headers)) return headers;
+  return headers.map(h => {
+    if (REDACT_KEYS.some(r => h.key.toLowerCase().includes(r.toLowerCase()))) {
+      return { key: h.key, value: '***REDACTED***' };
+    }
+    return h;
+  });
+}
+
+/**
+ * 脱敏 URL（保留路径和 host，redact query 参数）
+ * @param {string} url
+ * @returns {string}
+ */
+export function redactUrl(url) {
+  if (typeof url !== 'string') return url;
+  return url.replace(
+    /([?&])(token|password|verifyCode|code|apiKey|secret)=([^&\s]+)/g,
+    '$1$2=***'
+  );
+}
+
+/**
+ * 脱敏 JSON 字符串中的敏感字段（用于已经序列化的字符串）
+ * @param {string} jsonStr
+ * @returns {string}
+ */
+export function redactJsonString(jsonStr) {
+  if (typeof jsonStr !== 'string') return jsonStr;
+  return redactString(jsonStr);
+}

package/standard-skill/local-browser-test/lib/report-retain.js

@@ -0,0 +1,84 @@
+/**
+ * v4 retain 策略：保留最近 N 次 + 最近 N 天 + 失败永久保留
+ *
+ * 设计：
+ *   - retainRuns：保留最近 N 次 run（按 mtime 倒序）
+ *   - retainRunsByDay：保留最近 N 天的 run
+ *   - retainFailedForever：失败的 run 永久保留
+ *   - 超出范围的 run 删 runs/ 下目录
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULTS = {
+  retainRuns: 30,
+  retainRunsByDay: 7,
+  retainFailedForever: true
+};
+
+/**
+ * 应用 retain 策略
+ * @param {string} reportsDir
+ * @param {object} options
+ * @returns {{kept: number, removed: number}}
+ */
+export function applyRetain(reportsDir, options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+  const runsDir = path.join(reportsDir, "runs");
+  const failedDir = path.join(reportsDir, "runs-failed");
+
+  const allRuns = listRuns(runsDir).sort((a, b) => b.mtime - a.mtime);
+  const failedRuns = listRuns(failedDir);
+
+  // 计算保留集合
+  const keepByCount = new Set(allRuns.slice(0, opts.retainRuns).map((r) => r.id));
+  const cutoff = Date.now() - opts.retainRunsByDay * 24 * 3600 * 1000;
+  const keepByDay = new Set(allRuns.filter((r) => r.mtime >= cutoff).map((r) => r.id));
+  const keepFailed = new Set(failedRuns.map((r) => r.id));
+  const keep = new Set([...keepByCount, ...keepByDay, ...keepFailed]);
+
+  // 删除不在 keep 集合的
+  let removed = 0;
+  for (const run of allRuns) {
+    if (!keep.has(run.id)) {
+      fs.rmSync(run.path, { recursive: true, force: true });
+      removed++;
+    }
+  }
+
+  return { kept: keep.size, removed, total: allRuns.length };
+}
+
+/**
+ * 把失败的 run 归档到 runs-failed/（永久保留）
+ * @param {string} runId
+ * @param {string} runDir
+ * @param {string} failedDir
+ */
+export function archiveFailedRun(runId, runDir, failedDir) {
+  fs.mkdirSync(failedDir, { recursive: true });
+  const target = path.join(failedDir, runId);
+  if (fs.existsSync(target)) {
+    // 已存在同名失败 run：覆盖（少见）
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+  fs.renameSync(runDir, target);
+}
+
+function listRuns(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => {
+      try {
+        return fs.statSync(path.join(dir, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .map((name) => ({
+      id: name,
+      path: path.join(dir, name),
+      mtime: fs.statSync(path.join(dir, name)).mtimeMs
+    }));
+}

package/standard-skill/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/standard-skill/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/standard-skill/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/standard-skill/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/standard-skill/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);
+            });
+        });
+    }
+}