---
name: whart-test
description: WHartTest测试管理平台工具集。用于管理项目、模块、测试用例、测试截图和项目文件附件的增删改查。当用户需要操作测试用例、查询项目信息、上传截图、上传/下载/预览/删除项目文件、校验 file_ids 或管理文件清理设置时使用。
---

# WHartTest 测试管理平台

## 快速开始

```bash
# 设置环境变量
export WHARTTEST_BACKEND_URL="http://your-backend:8000"
export WHARTTEST_API_KEY="your-api-key"

# 执行操作（支持 whart_tools.py 与 whart_test_tools.py 别名）
python whart_tools.py --action <action_name> [--参数名 参数值]
```

## 可用操作

### 项目管理

| Action | 描述 | 参数 |
|--------|------|------|
| `get_projects` | 获取所有项目列表 | 无 |
| `get_modules` | 获取项目下的模块列表 | `--project_id` |
| `add_module` | 新增用例模块 | `--project_id`, `--name`, `--parent_id` (可选) |

### 用例管理

| Action | 描述 | 参数 |
|--------|------|------|
| `get_levels` | 获取用例等级列表 | 无 |
| `get_testcases` | 获取模块下的用例列表 | `--project_id`, `--module_id` |
| `get_testcase_detail` | 获取用例详情 | `--project_id`, `--case_id` |
| `add_testcase` | 新增测试用例 | `--project_id`, `--module_id`, `--name`, `--level`, `--precondition`, `--steps`, `--notes`, `--review_status`, `--test_type`, `--ui_test_case_id`, `--execution_mode` |
| `edit_testcase` | 编辑测试用例（支持关联/解绑 UI 自动化用例） | `--project_id`, `--case_id`, `--name`, `--level`, `--module_id`, `--precondition`, `--steps`, `--notes`, `--review_status`, `--test_type`, `--ui_test_case_id`, `--execution_mode`, `--is_optimization` |

### 截图管理

| Action | 描述 | 参数 |
|--------|------|------|
| `upload_screenshot` | 上传单张截图 | `--project_id`, `--case_id`, `--file_path`, `--title`, `--description`, `--step_number`, `--page_url` |
| `upload_screenshots` | 批量上传截图 | `--project_id`, `--case_id`, `--file_paths`(逗号分隔), `--title`, `--description`, `--step_number`, `--page_url` |

**截图路径约定**：自动化技能（如 `playwright-skill`、`browser-use`）生成的截图应优先保存到 `SCREENSHOT_DIR` 环境变量指定的目录。上传时只需传入文件名（无需路径），系统会优先从 `SCREENSHOT_DIR` 查找；若未命中，会再回退到常见临时截图目录做兼容搜索。

**单张上传**：`--file_path "case_11_step1.png"`
**批量上传**：`--file_paths "step1.png,step2.png,step3.png"`（最多10张，逗号分隔）

### 文件管理

| Action | 描述 | 参数 |
|--------|------|------|
| `list_files` | 获取项目文件列表 | `--project_id`, `--page`, `--page_size`, `--search`, `--status`, `--extension`, `--mime_type`, `--ordering` |
| `get_file_detail` | 获取文件详情 | `--project_id`, `--file_id` |
| `upload_file` | 上传单个项目文件 | `--project_id`, `--file_path` |
| `upload_files` | 批量上传项目文件 | `--project_id`, `--file_paths`(逗号分隔) |
| `validate_files` | 校验 file_ids 是否存在、属于项目且状态可用 | `--project_id`, `--file_ids`(JSON数组或逗号分隔) |
| `get_file_references` | 获取文件引用详情 | `--project_id`, `--file_id` |
| `delete_file` | 删除项目文件；被引用文件由后端软删除 | `--project_id`, `--file_id` |
| `get_file_settings` | 获取项目文件管理设置 | `--project_id` |
| `update_file_settings` | 更新自动清理设置 | `--project_id`, `--auto_delete_on_unbind`, `--auto_delete_zero_refs` |
| `cleanup_unreferenced_files` | 立即清理无引用项目文件 | `--project_id` |
| `download_file` | 下载文件到本地 | `--project_id`, `--file_id`, `--output_path` 或 `--output_dir` |
| `preview_file` | 预览文件；文本直接返回，二进制可保存 | `--project_id`, `--file_id`, `--output_path`(可选) |

**文件 ID 约定**：上传文件后返回的 `id` / `file_id` 可传给接口自动化、UI 自动化或智能体对话中的 `file_ids` 字段。使用前可通过 `validate_files` 校验。

**设置布尔值**：`--auto_delete_on_unbind` 与 `--auto_delete_zero_refs` 使用 `true` / `false`。

### 绑定的 UI 自动化用例与执行模式

- `--ui_test_case_id`：绑定的 UI 自动化用例 ID（整数）。若传已存在的 UI 用例 ID 则建立关联；传空或解除关联时可传对应值。
- `--execution_mode`：用例默认执行模式，可选值：
  - `hybrid` - 智能双模执行（脚本优先 + 失败自动介入自愈，默认）
  - `script_only` - 仅执行 UI 自动化脚本
  - `ai_only` - 纯 AI 探索执行

### 审核状态

`--review_status` 可选值：
- `pending_review` - 待审核（默认）
- `approved` - 通过
- `needs_optimization` - 优化
- `optimization_pending_review` - 优化待审核
- `unavailable` - 不可用

### 测试类型

`--test_type` 可选值：
- `smoke` - 冒烟测试
- `functional` - 功能测试（默认）
- `boundary` - 边界测试
- `exception` - 异常测试
- `permission` - 权限测试
- `security` - 安全测试
- `compatibility` - 兼容性测试

`--is_optimization` 标志（布尔型，无需传值）：在 edit_testcase 时带上此标志，会自动将状态设为 `optimization_pending_review`（优化待审核），用于AI优化后的用例提交。**一次调用即可完成编辑+状态更新。**
- 正确用法：`python whart_tools.py --action edit_testcase --project_id 1 --case_id 51 ... --is_optimization`
- 错误用法：`--is_optimization true`（不要传值）

## 使用示例

```bash
# 获取项目列表
python whart_tools.py --action get_projects

# 获取项目1的模块
python whart_tools.py --action get_modules --project_id 1

# 新增用例模块
python whart_tools.py --action add_module --project_id 1 --name "新功能模块"

# 新增子用例模块
python whart_tools.py --action add_module --project_id 1 --name "子功能模块" --parent_id 10

# 获取用例列表
python whart_tools.py --action get_testcases --project_id 1 --module_id 5

# 新增用例
python whart_tools.py --action add_testcase \
  --project_id 1 \
  --module_id 5 \
  --name "登录功能测试" \
  --level P0 \
  --precondition "用户已注册" \
  --steps '[{"step_number":1,"description":"输入用户名","expected_result":"用户名显示"}]' \
  --notes "冒烟测试"

# 上传单张截图
python whart_tools.py --action upload_screenshot \
  --project_id 1 \
  --case_id 10 \
  --file_path "step1.png" \
  --title "登录页面截图" \
  --step_number 1

# 批量上传截图
python whart_tools.py --action upload_screenshots \
  --project_id 1 \
  --case_id 10 \
  --file_paths "step1.png,step2.png,step3.png" \
  --title "登录测试截图"

# 上传项目文件
python whart_tools.py --action upload_file \
  --project_id 1 \
  --file_path "./需求说明.docx"

# 查询项目文件
python whart_tools.py --action list_files \
  --project_id 1 \
  --search "需求" \
  --page_size 20

# 校验附件 file_ids
python whart_tools.py --action validate_files \
  --project_id 1 \
  --file_ids "12,13"

# 下载项目文件
python whart_tools.py --action download_file \
  --project_id 1 \
  --file_id 12 \
  --output_dir "./downloads"

# 更新文件清理设置
python whart_tools.py --action update_file_settings \
  --project_id 1 \
  --auto_delete_on_unbind true \
  --auto_delete_zero_refs false
```

## 输出格式

所有操作返回 JSON 格式结果，便于解析处理。