yuhang-robot-platform 0.2.1

Robot Framework execution, device status listener, and MySQL uploader

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 仪表盘示例

项目结构

.
├── .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. 克隆仓库

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

2. 安装依赖

推荐使用虚拟环境：

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 文件配置运行参数。可先复制示例文件：

cp .env.example .env

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

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 测试

执行整个测试目录：

robot-platform run tests/

执行单个测试文件：

robot-platform run tests/demo.robot

指定 suite：

robot-platform run tests/ --suite Demo

指定测试用例：

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

按标签包含/排除：

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

指定输出文件：

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

2. 上传已有测试结果

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

robot-platform upload --output output.xml

3. 使用 shell 脚本运行

仓库中提供了脚本：

bash scripts/run_robot.sh tests/

该脚本会：

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

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

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

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

version = "0.2.0"

改成：

version = "0.2.1"

2. 清理旧构建产物

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

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

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

3. 安装构建和上传工具

python -m pip install --upgrade pip build twine

4. 构建分发包

在仓库根目录执行：

python -m build

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

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

5. 检查分发包

上传前建议先检查：

python -m twine check dist/*

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

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

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

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

[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 没问题后，再上传正式仓库：

python -m twine upload dist/*

8. 验证安装

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

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

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

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

9. 发布注意事项

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

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

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

命令行帮助

查看总帮助：

robot-platform --help

查看 run 子命令帮助：

robot-platform run --help

查看 upload 子命令帮助：

robot-platform upload --help

适用场景

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

当前版本

当前项目版本：

• 0.2.0

后续可改进方向

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

License

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