---
name: sut-explore
description: 访问被测系统探测新页面并生成可执行的 UI 自动化用例
---

访问被测系统（SUT）进行探测，发现未覆盖的功能模块，生成可直接执行的 UI 自动化测试用例。

## Usage

/sut-explore [目标功能关键词或模块]

## Description

通过真实浏览器访问被测系统，盘点已有用例覆盖范围，识别未覆盖功能，生成用例并反复验证直到可执行。

**功能：**
- 访问被测系统并登录
- 盘点现有用例库覆盖情况
- 识别未覆盖的功能点
- 通过浏览器探测真实 DOM/URL
- 生成可执行的 UI 自动化用例（写入 SQLite）
- 创建执行并迭代修复直到通过

**示例：**
```
/sut-explore 数据统计     # 探测数据统计模块
/sut-explore              # 交互式全量探测
```

## 前置条件

- 本地后端已启动：`uvicorn app.main:app --reload --port 8001`（工作目录 backend/）
- SUT 可访问：https://192.168.5.44
- 登录凭据：admin@xty / Ubains@13579，验证码固定 `csba`（见 [[test-platform-credentials]]）
- Chrome DevTools MCP 可用（用于真实浏览器探测）

## 执行步骤

### 1. 盘点现有用例覆盖
```bash
cd backend
python -c "
import sqlite3, json
conn = sqlite3.connect('data/test_platform.db')
cur = conn.cursor()
# 查所有模块及用例数
cur.execute('SELECT module_id, count(*) FROM test_cases GROUP BY module_id')
# 查指定功能关键词的用例数
cur.execute(\"SELECT count(*) FROM test_cases WHERE name LIKE '%会议概览%'\")
"
```
判断覆盖情况：**找到 0 个用例的关键词 = 未覆盖功能**。

### 2. 浏览器探测（Chrome DevTools MCP）
1. `navigate_page` 到 `https://192.168.5.44/` → 登录页
2. `fill_form` 填 手机号/密码/验证码 → `click` 登录按钮 → 可能弹"同意协议"对话框 → `click` 确定
3. `take_snapshot` 查看首页"常用功能"区域，**所有功能入口一次列出**，可直接发现未覆盖功能
4. 点击目标功能入口 → 从地址栏获取**真实直达 URL**（Hash 双重编码，直接复制勿手拼）
5. 在页面上 `evaluate_script` 探测 DOM 结构：
   - 所有 `input` 及其 `value/placeholder/readonly`（下拉框）
   - 所有 `button` 及其图标 class（查询/导出按钮常为空文本）
   - 标题/小部件文本

### 3. 生成用例（写 SQLite）
- 写生成脚本到 `backend/scripts/generate_xxx_cases.py`，插入 `test_cases` 表
- **必须配置**：`case_type='ui'`、`status='active'`、`config={"auto_login": true, "headless": true}`
- **首步必须** `navigate` 直达 URL（不要 click 菜单，headless 下微前端菜单不稳定）
- 步骤 JSON 用 `ensure_ascii=False` 序列化
- 断言选择器参照「踩坑清单」（见下）

### 4. 创建执行并验证
```bash
# 用 python requests（不要用 curl 中文 body，会 400）
python -c "
import requests, json
ids = [...]  # 用例 ID 列表
r = requests.post('http://localhost:8001/api/executions', json={'case_ids': ids, 'name': 'xxx验证'})
print(r.json()['id'])
"
# 启动
requests.post('http://localhost:8001/api/executions/{id}/run')
# 轮询（全量 10 用例约 400s）
requests.get('http://localhost:8001/api/executions/{id}')
# 查看失败详情
requests.get('http://localhost:8001/api/executions/{id}/results')
```

### 5. 迭代修复（2-3 轮）
- 首轮失败通常是导航/点击 → 改为 navigate 直达
- 后续失败是断言选择器不匹配 → 修正为真实 DOM 选择器
- 修复直接写脚本操作 DB（`UPDATE test_cases SET steps=? WHERE id=?`）
- 每轮创建新执行，直到 100% 通过

## 踩坑清单（务必对照）

1. **Element UI 下拉框**：`el-select` 渲染为 `<input readonly>`，断言用
   `input[readonly][value="日"]` 优先，兜底 `input[readonly][placeholder*="选择"]`
2. **图标按钮**：查询/导出按钮是纯图标（`<i class="el-icon-download">`）无文本，
   用 `.el-icon-download` 或 `button.el-button--primary`
3. **navigate 直达**：首页 `.block` 菜单 headless 下不稳定，首步一律 navigate
4. **Hash URL 复制**：双重 hash 路由（`%2F`=`/`、`%23`=`#`），从浏览器地址栏复制完整 URL
5. **curl 中文 body 400**：Git Bash 会破坏 UTF-8，改用 `python requests.post(json=body)`
6. **config 必配 auto_login**：`{"auto_login": true, "headless": true}`
7. **page_url_mapping.json**：新增页面条目后需**重启 uvicorn**（单例不热加载）
8. **登录有协议弹窗**：登录后可能弹"同意《统一登录服务协议》"对话框，需点"确定"

详见 [[sut-explore-pitfalls]]（完整踩坑记录）。

## 安全规则
- 只探测、不修改 SUT 数据（筛选查询可做，删除/新增真实数据不可）
- 登录凭据不写入用例文件本身（在 config 或凭据中引用）
- 生成的脚本放在 `backend/scripts/`，可在本地重复执行