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

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

@@ -215,13 +215,18 @@ AI 直接构造测试计划 JSON：
 | click | 点击元素（兼容） | `selector`, `waitForNavigation` | `{ clicked, tagName }` |
 | type | 输入文本（兼容） | `selector`, `text`, `clear` | `{ typed, value }` |
 | waitFor | 等待条件 | `selector` 或 `url`, `timeout` | `{ matched, waited }` |
-| evaluate | 执行 JS | `expression` | `{ result }` |
+| evaluate | 执行 JS（浏览器端） | `expression`, `expectResult?`, `expectResultContains?`, `failOnFalsy?` | `{ result, passed, reason }` |
 | checkElement | 元素断言（兼容） | `selector`, `expect: {visible, minCount, maxCount, hasText}` | `{ passed, checks, elementCount }` |
 | findPage | 查找已打开的标签页 | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` | `{ found, url, title, totalPages }` |
-| findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
+| findFrame | 查找微前端 iframe | `frameSelector`(CSS选择器) 或 `frameUrlContains` 或 `frameContentContains` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
 | loginWait | 等待 SSO 登录完成 | `loginSelector`, `timeout`, `interval` | `{ loggedIn, elapsed, currentUrl }` |
 | aiAssert | 语义断言（截图+审查） | `assertion`, `filename` | `{ screenshotPath, assertion, needsVisualReview }` |
 | runTask | 高层任务 runner（批量动态菜单扫描） | `task: "menu-api-scan"`, `menuApiPattern`, `menuLimit`, `menuPathPrefix[]`, `menuFilter[]`, `drawerTriggerSelector`, `useNativeHover`, `apiCaptureOptions`, `continueOnFail` | `{ task, discovered, attempted, byOutcome, results[] }` |
+| **apiCall** | **API 直调（绕过 UI）** | `method`, `url`, `body?`, `headers?` | `{ status, data, passed }` |
+| **switchPage** | **多标签页切换** | `urlContains?`/`titleIncludes?`/`pageIndex?` | `{ passed, url, title }` |
+| **cdpScript** | **调用内置/已注册脚本** | `script`, `params?` | `{ acted, passed, ...result }` |
+| **rawScript** | **Node.js 端执行任意 async** | `code`, `params?` | `{ acted, passed, ...result }` |
+| **registerCdpScript** | **注册可复用脚本** | `name`, `code` | `{ registered, passed }` |
 
 ### 场景选择策略
 
@@ -246,14 +251,33 @@ AI 直接构造测试计划 JSON：
 
 ### 构造步骤的指导原则
 
-1. **selector 必须从用户代码中读取，不要猜测**
-   - 读代码中的 `id`、`className`、`data-testid`
-   - szcd 组件的 class 可通过 `get_component_full_profile` 获取
-2. **API 路径从代码中的接口调用读取**
-3. **checkElement 的 expect 从代码逻辑推断**
-   - columns 定义了 N 列 → `expect: { minCount: N }`（检查 th 数量）
-   - dataSource 有数据 → `expect: { minCount: 1 }`（检查行数）
-4. **compare 的 regions 从设计稿分析结果或组件布局推断**
+**⚠️ 强制流程：构造 test-case JSON 前必须先执行 DOM 预检查**
+
+1. **observe 检查目标页面 DOM 结构**
+   - 确认 frame 结构（主页面 + 子应用 iframe）
+   - 确认表格/表单/按钮的 selector
+   - 确认 setup.findFrame 的匹配方式（frameSelector/frameUrlContains）
+
+2. **evaluate 检查关键元素文字**
+   - 按钮文字（如“提 交”中间有空格，不能用“提交”匹配）
+   - Select 选项文字（如“AI知识主题库”可能与 UI 显示不一致）
+   - 表单字段 label（如“数据资源名称”vs“数据集名称”）
+   - 表格列头（确认列数和列名）
+
+3. **根据 DOM 检查结果构造 test-case JSON**
+   - selector 从 observe 获取（不猜测）
+   - 选项文字从 evaluate 获取（不猜测）
+   - 按钮文字从 evaluate 获取（注意空格）
+   - 无项目代码时，DOM 检查替代代码读取
+
+4. **act 文字匹配**
+   - `text=新建` → 模糊匹配（includes），可能误匹配“新建目录”
+   - `text==新建` → 精确匹配（===），只匹配文字恰好为“新建”的元素
+   - 按钮文字可能有空格（如“提 交”），evaluate 检查后再选择匹配方式
+
+5. **API 路径从代码中的接口调用读取，或从 API 文档获取**
+6. **checkElement 的 expect 从代码逻辑推断**
+7. **compare 的 regions 从设计稿分析结果或组件布局推断**
 
 ## 微前端测试指南（实战经验）
 
@@ -352,7 +376,7 @@ node "$EXECUTOR" \
   --output /tmp/browser-observe.json
 ```
 
-`observe` 输出 `frames`、`tree`、`interactiveElements[index]`、`selectorCandidates`、`bbox`、`state`。Agent 后续应优先使用 `index` 调用 `act`，不要从 DOM 树重新猜 selector。直接 `--action observe` 默认只连接用户已启动的真实浏览器 CDP；如确需无 CDP 时启动 headless 回退，追加 `--allow-launch`。
+`observe` 输出 `frames`、`tree`、`interactiveElements[index]`、`selectorCandidates`、`bbox`、`state`、`wujieContext`（含 `shadowBodyText` 全文 + `shadowBodyTextLength`）。Agent 后续应优先使用 `index` 调用 `act`，不要从 DOM 树重新猜 selector。直接 `--action observe` 默认只连接用户已启动的真实浏览器 CDP；如确需无 CDP 时启动 headless 回退，追加 `--allow-launch`。
 
 ### 观察后按 index 交互（主链路闭环）
 ```bash
@@ -416,6 +440,38 @@ node "$EXECUTOR" \
 
 计划内可直接在 `apiCapture` 后追加 `{ "type": "assertApi", "maxFailed": 0, "forbidStatusGte": 400 }`，会自动读取上一步捕获结果。
 
+### 浏览器端 JS 执行（构造 testCase 前提取表单元数据）
+```bash
+node "$EXECUTOR" \
+  --action evaluate \
+  --url-contains "platform.aicityos.com" \
+  --frame-index 1 \
+  --expression '(() => Array.from(document.querySelectorAll(".ant-form-item")).map(item => ({
+    label: item.querySelector(".ant-form-item-label")?.textContent?.trim() || "",
+    required: !!item.querySelector(".ant-form-item-required"),
+    error: item.querySelector(".ant-form-item-explain-error")?.textContent?.trim() || ""
+  })).filter(x => x.label))()' \
+  --fail-on-falsy \
+  --output /tmp/form-fields.json
+```
+
+`--action evaluate` 在目标 frame 中执行任意 JS 表达式（需用 IIFE 包裹），返回 `{ result, passed }`。这是构造 testCase JSON 前的核心步骤：**无源码依赖地提取页面表单元数据、校验错误、Select 选项列表等**。
+
+关键参数：
+- `--expression <js>`：执行的 JS 表达式（必填）
+- `--fail-on-falsy`：结果为 falsy 时标记 FAIL
+- `--expect-result-contains <text>`：结果 JSON 包含指定文本
+
+### 执行测试计划 JSON（ES Module 版）
+```bash
+node "$EXECUTOR" \
+  --action plan \
+  --plan-file /tmp/test-plan.json \
+  --output /tmp/browser-test-result.json
+```
+
+`--action plan` 使用 ES Module 执行器运行测试计划 JSON，支持全部步骤类型（包括 evaluate、antSelect 等）。与 `--action test-case` 的区别：plan 不走 dataset 循环，适合单次执行。
+
 ### 快速诊断（过渡兼容）
 ```bash
 NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
@@ -502,7 +558,8 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.
   --scroll down --scroll-amount 500
 ```
 选择器语法：
-- `text=Build` → 按文本内容查找（类似 Playwright text selector）
+- `text=Build` → 按文本内容模糊查找，多个匹配时选 innerText 最短的元素（叶子节点优先，避免命中父容器）
+- `text==Build` → 精确文本匹配（Playwright 风格），只匹配 innerText 完全相等的元素
 - `role=button` → 按 ARIA role 查找
 - `~ant-menu-item` → CSS class 模糊匹配（`[class*="ant-menu-item"]`）
 - `.my-class` → 精确 CSS 选择器
@@ -692,11 +749,15 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 | `formFill` | 批量填充 + 可选 `validateAfter` | `fields[]` |
 | `closeAllDropdowns` | 关闭所有下拉浮层 | - |
 
-**关键约束**：
-- Ant Select 必须 `mousedown` 触发（不是 click）
-- 选项异步渲染，内置 15×200ms 轮询
-- 每次操作前后自动 `closeAllDropdowns`，`act` 入口检测残留并预清理
-- 操作后 VERIFY `.ant-select-selection-item[title]` 回写
+**关键约束（6/22 反馈后更新）**：
+- Ant Select 必须 `mousedown` + `click` 触发（click 触发 React onChange）
+- 选项异步渲染，内置 poll 轮询（timeout 默认 3s，不限制 1.5s）
+- `closeAllDropdowns` 去掉 `body >` 限制（适配微前端浮层）+ 增加 300ms sleep
+- 选项点击后 mousedown + mouseup + **click**（三步组合）
+- VERIFY 全局兜底：marker 丢失时全局搜索 `.ant-select-selection-item`
+- VERIFY 检查 `title` + `innerText` + `textContent`（三重兜底）
+- `popupResolved` 变量提升到 for 循环外（避免作用域 bug）
+- 浮层选择器去掉 `body >` 限制（`.ant-select-dropdown` 而非 `body > .ant-select-dropdown`）
 
 ```json
 { "type": "antSelect", "field": "数据集名称", "option": "测试集A" }
@@ -732,6 +793,75 @@ node local-browser-executor.js --action test-case --test-case-file /tmp/case.jso
 }
 ```
 
+## 脚本执行能力分层
+
+| 层级 | 步骤类型 | 执行环境 | 能力 | 适用场景 |
+|------|---------|---------|------|---------|
+| 1 | evaluate | 浏览器端 | DOM 查询/操作 | 简单检查、点击元素 |
+| 2 | rawScript | Node.js 端 | 完整 puppeteer API | 跨 frame、等待、多标签页 |
+| 3 | cdpScript | Node.js 端 | 调用已注册脚本 | 复用通用交互模式 |
+| 4 | 内置 cdpScript | Node.js 端 | 预定义通用 UI 交互 | Drawer/Modal/表格等 |
+
+**evaluate**：浏览器端执行 JS，只能操作 DOM，不能等待/跨 frame/调用 puppeteer
+**rawScript**：Node.js 端执行 async 函数，接收 `(page, frame, params, browser)`，可调用所有 puppeteer API
+**registerCdpScript**：注册可复用脚本，后续通过 cdpScript 步骤按 name 调用
+**cdpScript**：调用 registerCdpScript 注册的脚本或内置脚本
+
+### 内置 cdpScript（通用 UI 交互模式）
+
+| script | 功能 | params |
+|--------|------|--------|
+| `drawer-action` | Drawer 操作 | `action: 'search'\|'select'\|'confirm'\|'cancel'`, `radioIndex?`, `searchText?`, `searchPlaceholder?` |
+| `modal-action` | Modal/Popconfirm 操作 | `action: 'confirm'\|'cancel'`, `buttonText?` |
+| `switch-tab` | 多标签页切换 | `urlContains?`, `titleIncludes?`, `pageIndex?` |
+| `wait-api` | 等待 API 响应 | `urlPattern`, `timeout?`, `method?` |
+| `get-table-data` | 提取表格数据 | `selector?`, `maxRows?` |
+
+**设计原则**：cdpScript 内置通用 UI 交互模式（跨项目复用），业务流程由 LLM 用 rawScript 动态生成
+
+```json
+// 内置 cdpScript 示例
+{ "type": "cdpScript", "script": "get-table-data", "params": { "maxRows": 5 } }
+{ "type": "cdpScript", "script": "drawer-action", "params": { "action": "select", "radioIndex": 0 } }
+{ "type": "cdpScript", "script": "drawer-action", "params": { "action": "confirm" } }
+{ "type": "cdpScript", "script": "modal-action", "params": { "action": "confirm" } }
+{ "type": "cdpScript", "script": "switch-tab", "params": { "urlContains": "localhost:8088" } }
+
+// rawScript 示例（LLM 动态生成业务逻辑）
+{ "type": "rawScript", "code": "async (page, frame, params, browser) => { var count = await frame.evaluate(() => document.querySelectorAll('tr').length); return { acted: true, passed: count > 0, rowCount: count, status: 'PASS' } }" }
+
+// registerCdpScript + cdpScript（先注册再调用）
+{ "type": "registerCdpScript", "name": "my-check", "code": "async (page, frame, params) => { ... }" }
+{ "type": "cdpScript", "script": "my-check", "params": { "id": "123" } }
+```
+
+### evaluate 增强
+
+```json
+// expectResult：精确匹配返回值
+{ "type": "evaluate", "expression": "...", "expectResult": "found" }
+
+// expectResultContains：包含匹配返回值
+{ "type": "evaluate", "expression": "...", "expectResultContains": "数据资源" }
+
+// failOnFalsy：返回 falsy 时标记 FAIL
+{ "type": "evaluate", "expression": "...", "failOnFalsy": true }
+```
+
+### apiCall（API 直调）
+
+```json
+{ "type": "apiCall", "method": "POST", "url": "http://localhost:8088/api/submit", "body": { "id": "123" } }
+// → { status: 200, data: { code: "200" }, passed: true }
+```
+
+### switchPage（多标签页切换）
+
+```json
+{ "type": "switchPage", "urlContains": "localhost:8088" }
+// → { passed: true, url: "http://localhost:8088/...", title: "..." }
+```
+
 ## 语义断言（expect）
 
 | assertion | 功能 |
@@ -762,20 +892,26 @@ node local-browser-executor.js --action test-case --test-case-file /tmp/case.jso
 {
     "title": "数据集创建 P0",
     "setup": {
-        "findFrame": { "contentContains": "数据集目录" }
+        "findFrame": { "frameUrlContains": "#/catalog/" }
     },
     "dataset": [{ "name": "A" }, { "name": "B" }],
     "steps": [
-        { "type": "apiCapture", "urlPattern": "/api/dataset", "wait": 5000, "includeAllTargets": true },
+        { "type": "navigate", "url": "http://localhost:8088/#/szc-ai-data/catalog/catalog-manage", "waitUntil": "domcontentloaded" },
+        { "type": "expect", "assertion": "locator.toBeVisible", "selector": ".ant-table", "timeout": 20000 },
         { "type": "antInput", "field": "名称", "value": "{{name}}" },
         { "type": "antSelect", "field": "类型", "option": "图像" },
-        { "type": "act", "click": "text=提交" },
+        { "type": "act", "click": "text==提 交" },
         { "type": "expect", "assertion": "validation.toPass" },
-        { "type": "expect", "assertion": "api.toAllPass", "scope": "current-frame" }
+        { "type": "expect", "assertion": "locator.toBeVisible", "selector": ".ant-table", "timeout": 15000 }
     ]
 }
 ```
 
+**findFrame 三种方案（按稳定性排序）**：
+- `frameSelector: "iframe"` — 基于 DOM 选择器（最稳定，推荐）
+- `frameUrlContains: "#/catalog/"` — 基于 URL 子串（navigate 后可能失效）
+- `frameContentContains: "数据集目录"` — 基于内容文字（页面未加载时不可用）
+
 **关键参数：**
 
 - `setup.findFrame.contentContains` — 一次定位子应用 frame