# udi-test-cli

**Repository Path**: Disss44/udi-test-cli

## Basic Information

- **Project Name**: udi-test-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-08
- **Last Updated**: 2025-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎉 UDI API 自动化测试工具

> 基于 YAML 的接口自动化测试 CLI 工具，为 HC-UDI 医疗器械追溯系统提供完整的 API 测试解决方案

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-1.0.0-orange.svg)](setup.py)

## 📋 目录

- [项目简介](#项目简介)
- [核心特性](#核心特性)
- [快速开始](#快速开始)
- [安装指南](#安装指南)
- [使用手册](#使用手册)
- [测试用例编写](#测试用例编写)
- [Mock服务器](#mock服务器)
- [项目结构](#项目结构)
- [常见问题](#常见问题)

---

## 项目简介

**UDI Test CLI** 是一个专为 HC-UDI（医疗器械唯一标识）系统设计的接口自动化测试工具。

### 系统架构

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   SAP系统   │────▶│  UDI平台    │◀────│   MES系统   │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
              ┌─────▼────┐  ┌────▼─────┐
              │ 生产线客户端│  │  云端平台  │
              └──────────┘  └──────────┘
```

###接口覆盖

| 模块 | 接口数 | 说明 |
|---|---|---|
| **Auth** | 1 | 认证登录 |
| **MES** | 4 | 物料、注册证、订单数据 |
| **Client** | 8 | 生产线打印标签流程 |
| **Cloud** | 2 | 云端数据同步 |
| **SAP** | 4 | 经销商、DI信息查询 |
| **AntiFake** | 1 | 防伪验证 |
| **合计** | **21** | **100%覆盖** |

---

## 核心特性

✅ **YAML 驱动测试** - 测试用例使用 YAML 编写，语法简洁直观，无需编程基础，支持注释和文档化

✅ **多种请求格式** - 支持 JSON、form-data、application/x-www-form-urlencoded，自动处理 Content-Type

✅ **查询参数支持** - 优雅处理 GET 请求的 params 参数，自动 URL 编码，支持数组和嵌套对象

✅ **多环境管理** - 支持 dev/test/prod/mock 多环境配置切换，独立的 base_url 和 timeout 设置

✅ **并发执行控制** - 支持多线程并发运行，可自定义并发数（--workers），提升测试执行效率

✅ **失败自动重试** - 失败用例自动重试机制，可配置重试次数（--retry），提高测试稳定性

✅ **多格式测试报告** - 支持 HTML（交互式）、JSON（结构化）、Text（终端）三种格式，报告自动命名（test_report_YYYYMMDD_HHMMSS）

✅ **交互式HTML报告** - 吸顶标题、用例过滤（全部/通过/失败）、回到顶部按钮、美化滚动条、响应式布局

✅ **完整日志系统** - 终端彩色输出 + 文件持久化（logs/log_YYYYMMDD_HHMMSS.log），支持 INFO/ERROR/DEBUG 级别，日志自动归档

✅ **JSONPath 数据提取** - 强大的数据提取能力，支持嵌套对象、数组索引、通配符，提取数据可在后续用例中引用

✅ **丰富断言类型** - 15+ 种断言：相等/不等、包含、正则、类型匹配、数值比较、集合断言、长度断言、JSONPath 断言

✅ **变量引用系统** - 支持上下文变量（提取的数据）、环境变量（系统变量）、动态变量引用（${variable}）

✅ **标签过滤功能** - 支持按标签筛选用例（smoke/regression/P0/P1），灵活组织测试执行

✅ **模块化用例结构** - 按模块分目录，每个接口一个独立文件，遵循统一命名规范（{模块}/{序号}_{接口名}.yaml）

✅ **Postman 集合转换** - 自动转换 Postman Collection 为 YAML 测试用例，快速迁移已有测试

✅ **内置 Mock 服务器** - FastAPI 实现的完整 Mock 服务器，覆盖 21 个 HC-UDI 接口，支持 JWT 认证和数据持久化

✅ **跨平台兼容** - 完全支持 Linux/macOS/Windows，针对 Windows 优化依赖配置（PyYAML 6.0.1+、pydantic 2.10+）

✅ **请求/响应详情** - 自动记录完整的请求和响应信息，包括 headers、body、status_code，便于调试分析

✅ **性能统计分析** - 自动统计平均耗时、最快/最慢用例，提供性能基线数据

✅ **用例语法验证** - 内置 YAML 语法验证工具（uditest case validate），确保用例格式正确

---

## 快速开始

### 1. 安装

```bash
# 进入项目目录
cd /opt/udi/udi-test-cli

# 安装依赖
pip install -r requirements.txt

# 安装工具（开发模式）
pip install -e .

# 验证安装
uditest --version
```

### 2. 启动 Mock 服务器

```bash
cd mock_server
python3 main.py
```

服务器将运行在 `http://127.0.0.1:3004`

### 3. 运行测试

```bash
# 运行所有测试
uditest run testcases/mock/ --env mock

# 运行单个模块
uditest run testcases/mock/auth/ --env mock

# 运行单个接口测试
uditest run testcases/mock/auth/01_login_success.yaml --env mock

# 生成 HTML 报告（自动命名：test_report_YYYYMMDD_HHMMSS.html）
uditest run testcases/mock/ --env mock --report html

# 指定输出路径
uditest run testcases/mock/ --env mock --report html --output my_report.html
```

### 4. 快速请求测试

```bash
# 测试登录接口
uditest req POST /api/v1/auth/login \
  -d '{"loginName":"test_admin","password":"12345678"}' \
  --env mock
```

---

## 安装指南

### 系统要求

- Python 3.8+
- pip 包管理器
- Linux / macOS / Windows

### 安装方式

#### 方式一：开发模式（推荐）

```bash
cd /opt/udi/udi-test-cli
pip install -r requirements.txt
pip install -e .
```

#### 方式二：直接安装

```bash
cd /opt/udi/udi-test-cli
pip install .
```

### 验证安装

```bash
# 查看版本
uditest --version

# 查看帮助
uditest --help

# 查看所有命令
uditest
```

### 常见问题

**Q: 找不到 uditest 命令**

```bash
# 确认安装
pip show udi-test-cli

# 检查 PATH
echo $PATH

# 重新安装
pip install -e .
```

**Q: Windows环境下PyYAML安装失败**

如果遇到 `AttributeError: cython_sources` 或编译错误：

```bash
# 方案1: 清理缓存后重新安装（推荐）
pip cache purge
pip install -r requirements.txt

# 方案2: 指定使用预编译版本
pip install --only-binary :all: pyyaml

# 方案3: 手动安装指定版本
pip install pyyaml>=6.0.1
```

**说明**: PyYAML 6.0在Windows上需要C编译器，6.0.1+提供了预编译wheel包。本项目已更新为6.0.1+版本。

**Q: 依赖安装失败**

```bash
# 升级 pip
pip install --upgrade pip

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

---

## 使用手册

### 核心命令

#### 1. run - 运行测试

```bash
# 基础用法
uditest run testcases/mock/

# 完整参数
uditest run testcases/mock/ \
  --env mock \              # 环境
  --filter smoke \          # 过滤标签
  --parallel 4 \            # 并发数
  --retry 2 \               # 重试次数
  --report html \           # 报告格式
  --output report.html \    # 输出路径
  --debug                   # 调试模式
```

#### 2. req - 快速请求

```bash
# GET 请求
uditest req GET /api/v1/users --env mock

# POST 请求（JSON）
uditest req POST /api/v1/auth/login \
  -d '{"loginName":"admin","password":"123"}' \
  --env mock

# 自定义请求头
uditest req GET /api/v1/users \
  -H "Authorization: Bearer token123"

# 从文件读取
uditest req POST /api/v1/data -d @data.json
```

#### 3. env - 环境管理

```bash
# 列出所有环境
uditest env list

# 切换环境
uditest env use mock

# 查看当前环境
uditest env show
```

#### 4. case - 用例管理

```bash
# 列出所有用例
uditest case list

# 过滤标签
uditest case list -f smoke

# 验证语法
uditest case validate testcases/

# 转换 Postman
uditest case convert HC-UDI.postman.json -o testcases/
```

#### 5. report - 报告管理

```bash
# 自动生成报告（默认保存到 reports/ 目录）
uditest run testcases/mock/ --env mock --report html
# 生成: reports/test_report_20251008_143025.html

# 生成 JSON 报告
uditest run testcases/mock/ --env mock --report json
# 生成: reports/test_report_20251008_143025.json

# 自定义输出路径
uditest run testcases/mock/ --env mock --report html -o my_report.html
```

**报告命名规范**：
- 格式：`test_report_YYYYMMDD_HHMMSS.{ext}`
- 示例：`test_report_20251008_143025.html`
- 目录：默认保存在 `reports/` 目录

---

## 测试用例编写

### YAML 基础结构

```yaml
test_cases:
  - name: 用例名称                    # 必填
    description: 用例描述             # 可选
    priority: P0                     # P0/P1/P2
    tags: [smoke, regression]        # 标签列表

    api:
      method: POST                   # HTTP 方法
      url: /api/v1/resource          # 请求路径
      headers:                       # 请求头
        Content-Type: application/json
        Authorization: Bearer ${token}
      params:                        # 查询参数（GET请求）
        page: 1
        size: 10
      body:                          # 请求体
        key: value

    extract:                         # 数据提取
      - token: data.accessToken
      - user_id: data.user.id

    validate:                        # 断言
      - eq: [status_code, 200]
      - contains: [body.message, success]
```

### 数据提取示例

```yaml
extract:
  # 简单提取
  - token: data.accessToken

  # 嵌套提取
  - user_name: data.user.profile.name

  # 数组提取
  - first_id: data.items[0].id

  # 提取所有
  - all_names: data.items[*].name
```

### 断言类型

```yaml
validate:
  # 相等/不等
  - eq: [status_code, 200]
  - ne: [body.error, null]

  # 包含/不包含
  - contains: [body.message, success]
  - not_contains: [body.data, error]

  # 正则匹配
  - regex: [body.email, "^[a-zA-Z0-9@.]+$"]

  # 类型断言
  - type_match: [body.data.id, int]
  - type_match: [body.data.items, list]

  # 数值比较
  - gt: [body.count, 0]              # 大于
  - gte: [body.total, 100]           # 大于等于
  - lt: [body.page, 10]              # 小于
  - lte: [body.size, 20]             # 小于等于

  # 集合断言
  - in: [body.status, [success, pending]]
  - not_in: [body.error, [404, 500]]

  # 长度断言
  - length: [body.data.items, 10]

  # JSONPath 断言
  - jsonpath: [$.data.id, not_null]
```

### 变量引用

```yaml
# 引用提取的变量
api:
  headers:
    Authorization: Bearer ${token}   # 前面提取的 token
  body:
    userId: ${user_id}               # 前面提取的 user_id

# 引用环境变量
api:
  headers:
    API-Key: ${API_KEY}              # 系统环境变量
```

### 测试用例命名规范

**目录结构**: 按模块分目录，每个接口一个独立文件

**格式**: `{模块}/{序号}_{接口名}.yaml`

```
testcases/mock/
├── auth/          # 认证模块（3个接口）
├── mes/           # MES模块（4个接口）
├── client/        # 客户端模块（8个接口）
├── cloud/         # 云端模块（2个接口）
├── sap/           # SAP模块（4个接口）
└── antifake/      # 防伪模块（1个接口）
```

**命名规则**:
- 目录名：小写英文模块名（auth、mes、client等）
- 文件名：`{序号}_{接口英文名}.yaml`
- 序号：01-99（两位数字，便于排序）
- 接口名：小写英文，下划线分隔，描述性强

**示例**:
- `auth/01_login_success.yaml` - 成功登录
- `mes/01_material.yaml` - 物料主数据
- `client/05_start_tag.yaml` - 开始打印标签
- `sap/01_dealer.yaml` - 经销商数据

### 完整示例

```yaml
# testcases/mock/auth/01_login_success.yaml
# 模块: Auth (认证)
# 接口: POST /api/v1/auth/login
# 描述: 用户登录认证，成功获取 token

test_cases:
  - name: 成功登录获取token
    description: 使用正确的用户名和密码登录
    priority: P0
    tags: [smoke, auth, mock]
    api:
      method: POST
      url: /api/v1/auth/login
      headers:
        Content-Type: application/json
      body:
        loginName: test_admin
        password: "12345678"
    extract:
      - token: data.accessToken
      - user_id: data.user.userId
    validate:
      - eq: [status_code, 200]
      - eq: [body.code, 200]
      - contains: [body.message, "成功"]
      - type_match: [body.data.accessToken, str]
```

---

## Mock服务器

### 简介

内置 FastAPI Mock 服务器，提供 21 个 HC-UDI 接口的完整模拟。

### 安装依赖

```bash
# 安装 Mock 服务器依赖
pip install -r mock_server/requirements.txt
```

**注意**:
- Mock 服务器需要 `pydantic>=2.10.0`，该版本提供 Windows 预编译 wheel，无需 Rust 编译器
- 已针对 Windows 优化依赖配置，自动跳过不兼容的性能优化包（uvloop/httptools）

### 启动服务器

```bash
cd mock_server
python3 main.py
```

服务器地址: `http://127.0.0.1:3004`

### 特性

- ✅ 完整的 21 个 API 接口
- ✅ SQLite 数据库持久化
- ✅ JWT 认证机制
- ✅ 统一响应格式
- ✅ 自动 API 文档

### API 文档

访问 `http://127.0.0.1:3004/docs` 查看 Swagger 文档

### 默认测试账号

```
用户名: test_admin
密码: 12345678
```

---

## 项目结构

```
udi-test-cli/
├── udi_test/                      # 核心代码
│   ├── cli.py                    # CLI 入口
│   ├── runner.py                 # 测试运行器
│   ├── http_client.py            # HTTP 客户端
│   ├── yaml_loader.py            # YAML 加载器
│   ├── validator.py              # 断言校验器
│   ├── extractor.py              # 数据提取器
│   ├── config.py                 # 配置管理
│   ├── reporter.py               # 报告生成器
│   ├── converter.py              # Postman 转换
│   └── initializer.py            # 项目初始化
├── mock_server/                   # Mock 服务器
│   ├── main.py                   # 服务器入口
│   ├── database/                 # 数据库模块
│   ├── models/                   # 数据模型
│   ├── routers/                  # API 路由
│   └── services/                 # 业务服务
├── testcases/                     # 测试用例
│   └── mock/                     # Mock环境用例
│       ├── auth/                 # 认证测试（3个接口）
│       ├── mes/                  # MES测试（4个接口）
│       ├── client/               # 客户端测试（8个接口）
│       ├── cloud/                # 云端测试（2个接口）
│       ├── sap/                  # SAP测试（4个接口）
│       └── antifake/             # 防伪测试（1个接口）
├── config/                        # 配置文件
│   └── config.yaml               # 环境配置
├── reports/                       # 测试报告
├── setup.py                       # 打包配置
├── requirements.txt               # 依赖清单
└── README.md                      # 本文档
```

---

## 常见问题

### 测试相关

**Q: 如何运行单个测试用例？**

```bash
# 运行单个接口测试
uditest run testcases/mock/auth/01_login_success.yaml --env mock

# 运行整个模块
uditest run testcases/mock/auth/ --env mock
```

**Q: 如何并发运行测试？**

```bash
uditest run testcases/mock/ -p 4  # 4个并发
```

**Q: 如何生成 HTML 报告？**

```bash
# 自动生成（推荐）- 自动命名为 test_report_YYYYMMDD_HHMMSS.html
uditest run testcases/mock/ --report html

# 自定义文件名
uditest run testcases/mock/ --report html -o reports/test.html
```

### Mock 服务器

**Q: Mock 服务器启动失败？**

```bash
# 检查端口占用
lsof -i :3004

# 修改端口
# 编辑 mock_server/main.py 中的 port 参数
```

**Q: Windows环境下pydantic安装失败？**

如果遇到 "Cargo, the Rust package manager, is not installed" 错误：

```bash
# 方案1: 清理缓存后重新安装（推荐）
pip cache purge
pip install -r mock_server/requirements.txt

# 方案2: 手动安装指定版本
pip install pydantic>=2.10.0

# 方案3: 指定使用预编译版本
pip install --only-binary :all: pydantic
```

**说明**: pydantic 2.0 在 Windows 上需要 Rust 编译器，2.10+ 提供了预编译 wheel。本项目已更新为 2.10+ 版本。

**Q: Windows环境下uvicorn安装失败？**

如果遇到 uvloop 或 httptools 编译错误：

```bash
# 不要使用 uvicorn[standard]，直接安装
pip install uvicorn

# 或者按照项目配置安装（自动跳过不兼容包）
pip install -r mock_server/requirements.txt
```

**说明**: `uvicorn[standard]` 包含的 uvloop 和 httptools 在 Windows 上需要编译。本项目已配置环境标记，Windows 上自动跳过这些包。

**Q: 数据库错误？**

```bash
# 删除旧数据库
rm mock_server/database/udi.db

# 重启服务器（会自动重建）
cd mock_server
python3 main.py
```

### 用例编写

**Q: YAML 语法错误？**

```bash
# 验证语法
uditest case validate testcases/

# 检查具体文件
uditest inspect testcases/mock/auth/01_login_success.yaml

# 检查整个模块
uditest case list -p testcases/mock/auth/
```

**Q: 变量未定义？**

确保变量已在前面的用例中提取：

```yaml
# 用例1: 提取变量
extract:
  - token: data.accessToken

# 用例2: 使用变量
api:
  headers:
    Authorization: Bearer ${token}
```

### 环境配置

**Q: 如何添加新环境？**

编辑 `config/config.yaml`:

```yaml
environments:
  dev:
    base_url: http://192.168.121.121:8110
    timeout: 30
  test:
    base_url: http://test.example.com
    timeout: 30
  prod:
    base_url: https://prod.example.com
    timeout: 60
```

---

## 技术栈

- **Python 3.8+** - 核心语言
- **Click** - CLI 框架
- **Requests** - HTTP 客户端
- **PyYAML** - YAML 解析
- **FastAPI** - Mock 服务器
- **SQLite** - 数据持久化

---

## 作者

HC-UDI 测试团队

---

## 许可

MIT License

---

## 更新日志

### v1.0.0 (2025-10-08)
- ✅ 完整覆盖 21 个 HC-UDI 接口
- ✅ 支持多种请求格式（JSON/form-data/urlencoded）
- ✅ 支持查询参数
- ✅ 内置 FastAPI Mock 服务器
- ✅ HTML/JSON/Text 多格式报告
- ✅ 统一命名规范
- ✅ 完整文档

---

**Happy Testing! 🎉**