Metadata-Version: 2.4
Name: yuhang-robot-platform
Version: 0.2.1
Summary: Robot Framework execution, device status listener, and MySQL uploader
Author: Yuhang Zhao
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: robotframework>=6.0
Requires-Dist: pymysql>=1.1.0
Requires-Dist: python-dotenv>=1.0.1

# yuhang-robot-platform

一个基于 **Python + Robot Framework** 的测试执行平台，用于：

- 执行 Robot Framework 测试用例
- 在执行过程中通过 Listener 上报设备状态
- 在执行完成后解析 `output.xml`
- 将测试结果上传到 **MySQL**

该项目适合用于设备自动化测试、持续集成测试结果归档、测试运行状态可视化等场景。

## 功能特性

- 支持通过命令行执行 Robot Framework 测试
- 支持指定 suite、test、include、exclude 等运行参数
- 支持在测试运行过程中更新设备执行状态
- 支持解析 Robot Framework 的 `output.xml`
- 支持将测试结果明细、suite 汇总、run 汇总写入 MySQL 数据库
- 支持通过 `.env` 文件配置运行环境
- 提供 shell 启动脚本，便于本地或 CI 环境调用
- 提供数据库初始化 SQL 与 Grafana 仪表盘示例

## 项目结构

```text
.
├── .env.example
├── README.md
├── pyproject.toml
├── docker-compose.yml
├── scripts/
│   └── run_robot.sh
├── sql/
│   └── init.sql
├── grafana/
│   └── Robot Device Detail.json
├── src/
│   └── yuhang_robot_platform/
│       ├── __init__.py
│       ├── cli.py
│       ├── config.py
│       ├── listener.py
│       ├── robot_runner.py
│       ├── runtime_context.py
│       └── uploader.py
└── tests/
    └── demo.robot
```

## 核心模块说明

### `cli.py`
命令行入口，注册了两个子命令：

- `robot-platform run`：运行 Robot 测试并自动上传结果
- `robot-platform upload`：上传已有的 `output.xml`

### `robot_runner.py`
负责组装并执行 Robot Framework 命令：

- 注入 listener：`yuhang_robot_platform.listener.DeviceStatusListener`
- 生成 `output.xml / log.html / report.html`
- 执行结束后在 `output.xml` 存在时自动调用上传逻辑
- 若 Robot 执行失败但仍生成 `output.xml`，仍可继续上传结果

### `listener.py`
Robot Framework Listener 实现，在测试运行过程中更新设备状态到 MySQL。

当前推荐的状态更新策略：

- `start_suite`：写入 `RUNNING`
- `start_test`：写入 `RUNNING`
- `end_test`：清理当前测试，但保持 `RUNNING`
- `end_suite`：仅更新上下文，避免过早写入 `IDLE`
- `close`：在整个执行结束后写入最终 `IDLE`

这样可以避免嵌套 suite 或多阶段执行时设备状态被提前置为空闲。

### `uploader.py`
负责解析 Robot 的执行结果，并写入 MySQL 表。

当前数据库结构包括：

- `robot_test_results`：测试明细
- `robot_test_suite_summary`：suite 维度汇总
- `robot_test_run_summary`：run 维度汇总
- `robot_device_status`：设备实时状态

### `runtime_context.py`
统一加载运行时上下文，包括：

- MySQL 连接信息
- Robot 输出文件路径
- 当前运行标识（run_id、build_id、job_name）
- 环境名、日志链接、报告链接
- 设备名、执行来源、主机名

### `config.py`
负责读取环境变量，并通过 `python-dotenv` 加载 `.env` 配置。

## 安装要求

- Python 3.9+
- MySQL
- Robot Framework 6.0+

## 安装方式

### 1. 克隆仓库

```bash
git clone https://github.com/yuhang-vaillant/yuhang-robot-platform.git
cd yuhang-robot-platform
```

### 2. 安装依赖

推荐使用虚拟环境：

```bash
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
```

项目依赖如下：

- `robotframework>=6.0`
- `pymysql>=1.1.0`
- `python-dotenv>=1.0.1`

## 配置说明

项目支持通过 `.env` 文件配置运行参数。可先复制示例文件：

```bash
cp .env.example .env
```

`.env.example` 当前默认示例如下：

```dotenv
MYSQL_HOST=192.168.50.106
MYSQL_PORT=3306
MYSQL_USER=user
MYSQL_PASSWORD=vaillant
MYSQL_DATABASE=test_report

ROBOT_OUTPUT_XML=output.xml
RUN_ID=run_001
BUILD_ID=build_001
JOB_NAME=nightly_robot
ENV_NAME=test

REPORT_URL=http://your-report-server/report.html
LOG_URL=http://your-report-server/log.html

DEVICE_NAME=
EXECUTION_SOURCE=manual
HOST_NAME=
```

### 主要环境变量说明

#### 数据库相关

- `MYSQL_HOST`：MySQL 主机地址，当前默认示例为 `192.168.50.106`
- `MYSQL_PORT`：MySQL 端口
- `MYSQL_USER`：MySQL 用户名，当前默认示例为 `user`
- `MYSQL_PASSWORD`：MySQL 密码，当前默认示例为 `vaillant`
- `MYSQL_DATABASE`：MySQL 数据库名，默认 `test_report`

#### Robot 执行相关

- `ROBOT_OUTPUT_XML`：Robot 输出 XML 文件路径
- `RUN_ID`：本次执行的唯一标识
- `BUILD_ID`：CI 构建编号
- `JOB_NAME`：任务名称
- `ENV_NAME`：环境名称，如 `test` / `staging` / `prod`

#### 报告链接相关

- `REPORT_URL`：测试报告地址
- `LOG_URL`：测试日志地址

#### 运行上下文相关

- `DEVICE_NAME`：设备名称，默认取主机名
- `EXECUTION_SOURCE`：执行来源，默认 `manual`
- `HOST_NAME`：主机名，默认自动获取

## 使用方法

## 1. 执行 Robot 测试

执行整个测试目录：

```bash
robot-platform run tests/
```

执行单个测试文件：

```bash
robot-platform run tests/demo.robot
```

指定 suite：

```bash
robot-platform run tests/ --suite Demo
```

指定测试用例：

```bash
robot-platform run tests/ --test "Login Success"
```

按标签包含/排除：

```bash
robot-platform run tests/ --include smoke --exclude unstable
```

指定输出文件：

```bash
robot-platform run tests/ --output output.xml --log log.html --report report.html
```

## 2. 上传已有测试结果

如果 `output.xml` 已经存在，可以直接上传：

```bash
robot-platform upload --output output.xml
```

## 3. 使用 shell 脚本运行

仓库中提供了脚本：

```bash
bash scripts/run_robot.sh tests/
```

该脚本会：

- 自动加载当前目录下的 `.env`
- 输出关键环境信息
- 调用 `robot-platform run`

也支持附加 Robot 运行参数，例如：

```bash
bash scripts/run_robot.sh tests/ --test "Login Success"
```

## 发布到 PyPI

如果你要把 `yuhang_robot_platform` 发布到 PyPI，建议按下面步骤执行。

### 1. 确认包配置

当前包配置在 `pyproject.toml` 中：

- 包名：`yuhang-robot-platform`
- Python 版本要求：`>=3.9`
- CLI 入口：`robot-platform = yuhang_robot_platform.cli:main`

每次发布前，先更新版本号，例如把：

```toml
version = "0.2.0"
```

改成：

```toml
version = "0.2.1"
```

### 2. 清理旧构建产物

```bash
rm -rf dist build src/*.egg-info
```

如果你不想删整个 `src/*.egg-info`，也可以只删除当前项目的：

```bash
rm -rf dist build src/yuhang_robot_platform.egg-info
```

### 3. 安装构建和上传工具

```bash
python -m pip install --upgrade pip build twine
```

### 4. 构建分发包

在仓库根目录执行：

```bash
python -m build
```

构建成功后，`dist/` 目录下通常会生成：

- `yuhang_robot_platform-<version>.tar.gz`
- `yuhang_robot_platform-<version>-py3-none-any.whl`

### 5. 检查分发包

上传前建议先检查：

```bash
python -m twine check dist/*
```

### 6. 上传到 TestPyPI（推荐先测试）

```bash
python -m twine upload --repository testpypi dist/*
```

如果你的环境还没有配置 PyPI 凭证，Twine 会提示输入用户名和密码。

也可以提前在 `~/.pypirc` 中配置，例如：

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = <your-pypi-token>

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = <your-testpypi-token>
```

### 7. 上传到正式 PyPI

确认 TestPyPI 没问题后，再上传正式仓库：

```bash
python -m twine upload dist/*
```

### 8. 验证安装

上传完成后，可在一个干净虚拟环境中验证：

```bash
python -m venv .venv-test
source .venv-test/bin/activate
pip install -U pip
pip install yuhang-robot-platform
robot-platform --help
```

如果是从 TestPyPI 安装，可使用：

```bash
pip install -i https://test.pypi.org/simple/ yuhang-robot-platform
```

### 9. 发布注意事项

- PyPI 上同一个版本号**不能重复上传**，每次发布都必须提升版本号。
- `README.md` 会作为项目主页说明的一部分展示，发布前建议确认格式正常。
- 建议先执行：

```bash
python -m build
python -m twine check dist/*
```

再进行正式上传。

## 运行流程

项目整体流程如下：

1. 加载 `.env` 和系统环境变量
2. 生成运行时上下文
3. 执行 Robot Framework 测试
4. Listener 在执行过程中持续更新设备状态
5. Robot 生成 `output.xml`
6. 上传器解析 `output.xml`
7. 将测试明细、suite 汇总、run 汇总写入 MySQL

## 数据库说明

仓库已提供初始化 SQL：

- `sql/init.sql`

当前代码依赖以下几张表：

### 1. `robot_device_status`

用于记录设备当前状态。

### 2. `robot_test_results`

用于保存测试结果明细。

### 3. `robot_test_suite_summary`

用于保存 suite 维度统计信息。

### 4. `robot_test_run_summary`

用于保存单次 run 的汇总信息。

## 示例测试

仓库内置了一个简单示例：

- `tests/demo.robot`

包含两个测试用例：

- `Login Success`
- `Login Failed`

可用于验证执行链路、报告生成以及上传流程是否正常。

## 命令行帮助

查看总帮助：

```bash
robot-platform --help
```

查看 `run` 子命令帮助：

```bash
robot-platform run --help
```

查看 `upload` 子命令帮助：

```bash
robot-platform upload --help
```

## 适用场景

- 设备测试平台结果归档
- 自动化测试执行状态上报
- CI/CD 测试结果入库
- 测试报告与设备状态联动展示

## 当前版本

当前项目版本：

- `0.2.0`

## 后续可改进方向

- 增加日志模块，替代 `print`
- 增加测试结果去重或覆盖策略
- 增加 CI 工作流示例
- 增加更完整的示例测试集

## License

当前仓库尚未声明 License，建议根据实际需要补充 `LICENSE` 文件。
