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

package/opencode-extension/skills/local-browser-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: local-browser-test
-description: 在用户真实 Chrome 中执行自动化测试，覆盖 P0 用例批量执行、深度表单填写、微前端测试、长任务生命周期、设计稿对比、JS 错误诊断。通过 puppeteer-core 连接 CDP，天然继承登录态/微前端环境。
+description: 在用户真实 Chrome 中执行自动化测试，覆盖测试用例批量执行、深度表单填写、微前端测试、长任务生命周期、设计稿对比、JS 错误诊断。通过 puppeteer-core 连接 CDP，天然继承登录态/微前端环境。
 compatibility:
   tools:
     - run_command
@@ -72,7 +72,7 @@ export EXECUTOR="$SKILL_DIR/local-browser-executor.js"
 
 ## 🎯 三种典型任务（场景驱动）
 
-### 任务 A：P0 用例批量执行（首选）
+### 任务 A：测试用例批量执行（首选）
 
 用户说"执行 P0 用例 / 批量测试 / 生命周期测试"时，**不要写 ad-hoc puppeteer 脚本**，构造 testCase JSON：
 
@@ -144,7 +144,7 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action api-capture --
 
 ```
 Agent / SKILL.md
-  → testCase JSON  ←  P0 用例首选入口
+  → testCase JSON  ←  测试用例首选入口
   → $SKILL_DIR/local-browser-executor.js  ($EXECUTOR)
   → $SKILL_DIR/lib/browser-engine.js  (executeTestCase + Ant 适配 + expect)
   → $SKILL_DIR/lib/ant-adapter.js     (Select/TreeSelect/Input/Radio/...)
@@ -672,14 +672,32 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
 - `--expect-result-contains <text>`：结果 JSON 包含指定文本
 
 ### 执行测试计划 JSON（ES Module 版）
+
+**⚠️ 禁用 `--action plan`（该分支提前 `process.exit`，不会生成 HTML 报告）**
+直接用 `--plan-file`：
+
 ```bash
 NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
-  --action plan \
   --plan-file /tmp/test-plan.json \
-  --output /tmp/browser-test-result.json
+  --config /path/to/config.yaml
+```
+
+工作区默认在 CWD 的 `.lbt/`，无需手动传 `--workspace`：
+
+```
+.lbt/
+├── config.yaml          ← 项目配置
+├── reports/             ← HTML 报告（趋势图 + 过滤 + 详情页 + 截图）
+│   ├── index.html
+│   └── runs/<id>/
+├── tmp/                 ← 执行过程临时文件（截图等）
+├── auth/                ← 保存的登录态
+└── plans/               ← 回归脚本
 ```
 
-`--action plan` 使用 ES Module 执行器运行测试计划 JSON，支持全部步骤类型（包括 evaluate、antSelect 等）。与 `--action test-case` 的区别：plan 不走 dataset 循环，适合单次执行。
+不传 `--workspace` 时默认 `cwd/.lbt`，也可用 `--workspace <dir>` 指定其他目录。
+
+与 `--action test-case` 的区别：plan 不走 dataset 循环，适合单次执行。
 
 ### 快速诊断（JS错误 + 网络 + 资源 + iframe）
 ```bash
@@ -726,12 +744,15 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
 ### 可选参数
 
 - `--cdp-url http://localhost:9222`：CDP 地址（默认 9222）
-- `--url <url>`：目标页面 URL（不存在则导航）
+- `--page-url <url>`：目标页面 URL（不存在则导航）
 - `--url-contains <keyword>`：按关键词查找已打开的页面
 - `--frame-url-contains <keyword>`：observe 时按 iframe URL 片段匹配目标 frame
 - `--frame-content-contains <keyword>`：observe 时按 iframe 文本内容匹配目标 frame
 - `--frame-index <n>`：observe 时按 frame 下标选择目标 frame
-- `--wait <ms>`：额外等待时间（默认 5000ms，微前端建议 15000）
+- `--plan-file <path>`：测试计划 JSON 文件路径
+- `--config <path>`：配置文件路径（如 config.yaml）
+- `--workspace <dir>`：工作区目录，默认 `cwd/.lbt`。存放 `reports/`（HTML 报告）、`tmp/`（临时文件）、`auth/`（登录态）、`plans/`（回归脚本）
+- `--wait <ms>`：额外等待时间（默认因 action 而异：api-capture 15000，其余 5000）
 - `--output <path>`：JSON 结果输出路径
 - `--output-dir <dir>`：截图/产物目录
 - `--filename <name>`：截图文件名
@@ -741,12 +762,41 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
 - `--click <selector>`：点击元素（支持 text=/role=/~）
 - `--type <text>`：输入文本
 - `--hover <selector>`：悬停元素
-- `--scroll <up|down|left|right>`：滚动方向
-- `--scroll-amount <px>`：滚动距离（默认 300）
-- `--screenshot-after`：交互后自动截图
+- `--expression <js>`：evaluate 执行的 JS 表达式（需 IIFE 包裹）
+- `--fail-on-falsy`：evaluate 结果为 falsy 时标记 FAIL
+- `--expect-result-contains <text>`：evaluate 结果包含指定文本
+- `--include-response-body`：api-capture 包含响应体
+- `--include-all-targets`：api-capture 监听全部 target（含非 frame 的 worker/extension）
+- `--reload`：api-capture 前重载页面
+- `--url-pattern <pattern>`：api-capture 按 URL 过滤
+- `--method <method>`：api-capture 按 HTTP 方法过滤
+- `--capture-file <path>`：assert-api 读取的捕获结果文件
+- `--max-failed <n>`：assert-api 允许的最大失败请求数
+- `--forbid-status-gte <code>`：assert-api 禁止的状态码阈值
+- `--required-url <pattern>`：assert-api 必需出现的 URL 模式
+- `--include-request-body`：api-capture 包含请求体
+- `--no-request-body`：api-capture 排除请求体
+- `--target-url-contains <text>`：api-capture 目标 frame URL 包含
 - `--interval <ms>`：watch 模式间隔（默认 5000）
 - `--max-rounds <n>`：watch 最大轮数（默认 60）
 - `--allow-launch`：根执行器 action 模式允许无 CDP 时启动 headless Chrome；默认不启用，优先保障真实用户浏览器链路
+- `--ci`：CI 模式（自动设置 screenshot=always, video=on, trace=on, retries=2）
+- `--retries <n>`：用例级重试次数
+- `--flaky-threshold <n>`：Flaky 测试阈值
+- `--screenshot <always|only-on-failure>`：截图策略
+- `--video <on|off|only-on-failure>`：录像策略
+- `--trace <on|off>`：trace 录制
+- `--record-har`：录制 HAR
+- `--storage-state <path>`：认证存储状态文件路径（用于 global-setup）
+- `--global-setup`：全局设置模式（保存登录态）
+- `--init-force`：强制初始化工作区
+- `--project <name>`：多环境项目选择
+- `--env <name>`：环境选择
+- `--tags <tag>`：按 tag 筛选用例
+- `--exclude-tags <tag>`：排除 tag
+- `--tag-mode <any|all>`：tag 匹配模式
+- `--no-retry-actions`：禁用写操作重试
+- `--no-reload`：diagnose 跳过页面重载
 
 ## AI 语义断言（aiAssert）
 
@@ -822,24 +872,47 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 - passed = total：全部通过
 - 有失败步骤：根据 `step` + `error` 字段定位代码问题
 
-### 结果文件结构
+### HTML 报告（推荐）
+
+传 `--workspace <dir>` 时自动生成 Playwright 风格 HTML 报告：
+
+```
+<workspace>/reports/
+├── index.html          ← 入口：趋势图 + 过滤 + 运行列表
+├── trend.json          ← 按日聚合数据
+└── runs/
+    └── <timestamp>-pid<N>/
+        ├── index.html  ← 详情页：步骤表格、截图、错误展开
+        ├── result.json ← 原始结果（脱敏）
+        └── screenshots/ ← 截图副本
+```
+
+入口支持交互过滤（状态 + 关键词搜索）、echarts 趋势图、详情页"返回列表"导航、截图展示。
+
+### 结果 JSON 结构（stdout）
 ```json
 {
     "planId": "xxx",
+    "description": "...",
     "mode": "connect",
+    "startTime": "2026-07-01T10:00:00.000Z",
+    "duration": "1583",
     "steps": [
-        { "index": 1, "step": "navigate", "status": "PASS", "duration": 1200, ... },
-        { "index": 2, "step": "screenshot", "status": "PASS", "duration": 500, ... },
-        { "index": 3, "step": "compare", "status": "PASS", "fidelity": 94.7, ... }
+        { "index": 1, "step": "navigate", "status": "PASS", "duration": "1200", ... },
+        { "index": 2, "step": "screenshot", "status": "PASS", "duration": "500",
+          "filepath": "/tmp/.../screenshot.png", ... }
     ],
     "summary": {
-        "total": 5, "passed": 4, "failed": 1,
-        "fidelity": 94.7
+        "total": "9", "passed": "9", "failed": "0",
+        "fidelity": null
     },
+    "browserInfo": { "mode": "connect", "cdpUrl": "...", "currentUrl": "...", "totalPages": 6 },
     "outputDir": "/tmp/browser-test-xxx"
 }
 ```
 
+注意：`startTime`（非 `startedAt`）、`duration`（非 `durationMs`）。HTML 报告器内部会把 `startTime` → `startedAt`、`duration` → `durationMs`、`summary.*` → `stats.*` 做字段归一化。
+
 ## 批量动态菜单扫描（runTask）
 
 适用场景：测试系统有 N 条动态路由（来自后端菜单接口），要逐条点击触发并验证接口是否返回 200。6/18 反馈中，AI 最终用 130 余条 `act --menu-path` + `api-capture` 手工组合走完 129 条菜单——`runTask` 把这套流水固化为单步骤。
@@ -966,7 +1039,7 @@ cat > /tmp/login.json <<EOF
 EOF
 
 # 3. 执行登录
-NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action plan --plan-file /tmp/login.json --url-contains "platform.aicityos.com" --wait 8000
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --plan-file /tmp/login.json --config /path/to/config.yaml
 ```
 
 **LLM 处理流程：**
@@ -1014,6 +1087,10 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action plan --plan-fi
 - ❌ **v20 格式**（生产环境，App-Bound Encryption）：需 Python `pywin32` + `cryptography` 方案
 - ⚠️ Windows 专属（DPAPI），macOS/Linux 需 Keychain/KWallet 方案
 
+## 已知技术债
+
+- **代码重复**：`normalizeForReport`（executor.js）与 `normalizeRunResult`（html-reporter.js）是相同字段归一化逻辑的两份拷贝。修改任何字段映射时必须同步两处。
+
 ## 反模式备忘（来自 6/17 + 6/18 实战反馈）
 
 | 错误做法 | 正确做法 | 原因 |

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

@@ -6,6 +6,7 @@
  */
 
 import fs from "node:fs";
+import path from "node:path";
 import { captureStorageState } from "./storage-state.js";
 import { redact } from "./redact.js";
 
@@ -19,7 +20,7 @@ export async function globalSetupTakeover(page, outputPath) {
 
   // 落盘前 redact（cookie value 也可能含敏感 token）
   const safe = redact(state);
-  fs.mkdirSync(fs.dirname(outputPath), { recursive: true });
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, JSON.stringify(safe, null, 2));
   console.log(`✓ storageState 已保存: ${outputPath}`);
   console.log(`  cookies: ${safe.cookies?.length ?? 0}, origins: ${safe.origins?.length ?? 0}`);