# hil-auto-test

**Repository Path**: elfbobo_admin_admin/hil-auto-test

## Basic Information

- **Project Name**: hil-auto-test
- **Description**: hil-auto-test：专注于自动化测试的开源项目，提供高效、可靠的测试框架和工具，支持多种编程语言和测试场景。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HIL Auto Test

基于 SSH 的远程自动化测试框架，提供 Web UI 管理界面，支持远程测试执行、循环测试、实时状态监控和报告生成。

## 功能特性

### Web UI 管理界面

- **测试配置编辑器** - 可视化编辑 pytest 配置（产品、版本、标题、测试目录等）
- **测试执行控制** - 一键启动/停止测试，支持单次执行和循环轮询
- **实时进度追踪** - SSE 实时推送测试进度，显示当前执行状态
- **报告查看器** - 内嵌 Allure HTML 报告和 PDF 测试报告

### 测试执行

- **远程 SSH 执行** - 通过 SSH 连接远程主机执行测试
- **循环测试模式** - 支持定时轮询执行，可配置间隔时间
- **失败重试机制** - 自动重试失败的测试用例
- **实时状态同步** - 前端实时显示测试进度和状态

### 报告生成

- **Allure HTML 报告** - 自动生成 Allure 测试报告
- **PDF 测试报告** - 生成包含测试摘要和详细步骤的 PDF 报告
- **测试汇总统计** - 通过/失败/跳过数量统计

### 状态监控

- **实时状态追踪** - 记录测试执行过程中的状态变化
- **历史状态查询** - 查询指定时间范围内的状态记录
- **状态时间轴可视化** - ECharts 图表展示状态时间轴
- **停机补全** - 服务重启时自动补全停机期间的 offline 记录
- **远程状态同步** - 将本地状态历史数据库截取后上传到远程服务器

### 远程状态同步

支持将本地 `status_history.db` 中的数据同步到远程服务器：

```bash
# 默认截取最近 120 小时的数据并上传
python api/api_readStatus.py

# 指定截取时长（分钟）
python api/api_readStatus.py 1440
```

该功能通过 SFTP 将截取的数据上传到远程 `{SSH_PROJECT_ROOT}/logs/` 目录，支持文件锁防止并发执行。

## 技术栈

| 类别 | 技术 |
|------|------|
| 后端 | Python 3.8+ / FastAPI / Uvicorn |
| 前端 | Vue 3 / TypeScript / Element Plus / ECharts |
| 测试框架 | pytest / allure-pytest / pytest-rerunfailures |
| 远程执行 | paramiko (SSH) |
| 报告生成 | Allure / ReportLab (PDF) |
| 数据存储 | SQLite |

## 环境要求

### 必需环境

| 软件 | 版本要求 | 说明 |
|------|----------|------|
| Python | 3.8+ | 后端运行环境 |
| Node.js | 16+ | 前端构建环境 |
| Java | 8+ | Allure 命令行工具依赖 |
| Allure 命令行工具 | 2.x | 生成 Allure 测试报告 |

### 远程服务器要求

- SSH 服务已启动
- Python 3.8+ 环境
- 项目代码已部署到远程服务器

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd hil-auto-test-1
```

### 2. 环境安装

**Windows (PowerShell)**

```powershell
.\start_env.ps1
```

**macOS / Linux (Bash)**

```bash
bash start_env.sh
```

脚本会自动完成以下操作：

#### 检查并安装运行环境

| 软件 | 说明 |
|------|------|
| Python 3.14 | 优先安装 3.14，未找到时提示安装或使用默认版本 |
| Node.js | 检测并安装 Node.js LTS 版本 |
| Java (OpenJDK 11) | Allure 报告工具的运行依赖 |
| Allure 命令行工具 | 通过 npm 全局安装 allure-commandline |

> 注：安装过程中会提示确认，可选择跳过自动安装

#### 配置项目环境

| 操作 | 说明 |
|------|------|
| 创建虚拟环境 | 在项目根目录创建 `venv/` 目录 |
| 安装 Python 依赖 | 从 `requirements.txt` 安装所有依赖包 |
| 创建必要目录 | `logs/`、`reports/allure-results/`、`reports/allure-report/` |
| 创建 pytest.ini | 如不存在则创建默认配置文件 |
| 创建 .env 文件 | 如不存在则从 `.env.example` 复制 |

#### 配置系统环境

- 自动配置 `JAVA_HOME` 环境变量
- 自动将 npm 全局 bin 目录添加到 PATH
- 配置 npm 使用国内镜像加速下载

### 3. 配置文件

复制 `.env.example` 为 `.env`：

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

编辑 `.env` 文件，配置 SSH 连接信息：

```ini
# 远程主机配置
SSH_HOST=192.168.1.100
SSH_PORT=22
SSH_USERNAME=test_user
SSH_PASSWORD=your_password_here
SSH_PROJECT_ROOT=/opt/ZONE/PythonProject/hil-auto-test

# 状态记录配置
STATUS_SNAPSHOT_INTERVAL=10
STATUS_CHECK_DAYS=30
STATUS_RETENTION_DAYS=60
STATUS_DELETE_DAYS=15
```

### 4. 启动服务

**Windows (PowerShell)**

```powershell
.\start_server.ps1
```

**macOS / Linux (Bash)**

```bash
bash start_server.sh
```

服务启动后访问：http://localhost:3000

### 5. 运行第一个测试

1. 打开浏览器访问 http://localhost:3000
2. 在 **测试配置** 区域编辑测试参数
3. 点击 **开始测试** 按钮
4. 在 **测试进度** 区域查看实时进度
5. 测试完成后在 **测试报告** 区域查看报告

## 配置详解

### 环境变量 (.env)

#### SSH 远程连接配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SSH_HOST` | 远程主机 IP 地址 | - |
| `SSH_PORT` | SSH 端口 | 22 |
| `SSH_USERNAME` | SSH 用户名 | - |
| `SSH_PASSWORD` | SSH 密码 | - |
| `SSH_PROJECT_ROOT` | 远程项目根目录 | - |

#### 状态记录配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `STATUS_SNAPSHOT_INTERVAL` | 状态快照间隔（秒） | 10 |
| `STATUS_CHECK_DAYS` | 补全检查天数（服务启动时检查最近 N 天的记录） | 30 |
| `STATUS_RETENTION_DAYS` | 数据保留总天数（超过此天数会清理旧记录） | 60 |
| `STATUS_DELETE_DAYS` | 超过保留期限时删除的天数 | 15 |

### pytest 配置 (pytest.ini)

```ini
[pytest]
testpaths = tests/test_cases_short
addopts = -v --alluredir=reports/allure-results --clean-alluredir --reruns 3

# 测试项目配置
product = PHEV-JAKKO
version = 1.0.0
title = 测试标题
python_classes = Test*
python_functions = test_*
python_files = test_*.py
```

| 配置项 | 说明 |
|--------|------|
| `testpaths` | 测试用例目录 |
| `addopts` | pytest 命令行参数 |
| `product` | 产品名称（显示在报告中） |
| `version` | 版本号（显示在报告中） |
| `title` | 测试标题（显示在报告中） |
| `--reruns` | 失败重试次数 |

### Web 服务配置

后端服务默认端口：`8000`

前端开发服务器默认端口：`3000`

可在 `server/backend/main.py` 和 `server/frontend/vite.config.ts` 中修改。

## 使用指南

### Web UI 操作

#### 测试配置页面

1. 编辑 **产品名称**、**版本号**、**测试标题**
2. 选择 **测试用例目录**（下拉选择）
3. 配置 **失败重试次数**
4. 点击 **保存配置** 保存设置

#### 测试执行页面

1. **单次测试** - 点击「开始测试」执行一次测试
2. **循环测试** - 勾选「启用循环测试」，设置间隔时间后启动
3. **停止测试** - 测试运行中可点击「停止测试」中断

#### 报告查看页面

- **Allure 报告** - 切换到「Allure 报告」标签查看交互式报告
- **PDF 报告** - 切换到「PDF 报告」标签查看生成的 PDF 报告
- 报告会在测试完成后自动刷新

#### 状态监控页面

- **实时状态** - 查看台架实时状态，含仪表盘和折线图
  - 数据来源：`status_history.db`
  - 时间窗口：30分钟 / 1小时 / 6小时 / 24小时 / 120小时
  - 刷新按钮：重新从数据库读取数据并渲染
- **历史状态** - 查看历史统计数据，支持 7/30/60 天时间范围
  - 数据来源：`daily_statistics.db`
  - 刷新按钮：先同步 `status_history.db` 到 `daily_statistics.db`，再读取渲染
  - 定时同步：每天 8:00、16:00 自动执行同步任务

### 循环测试

1. 勾选「启用循环测试」
2. 设置「循环间隔」时间（分钟）
3. 点击「开始测试」
4. 系统会按照设定的间隔自动执行测试
5. 在「等待下一轮」倒计时中可以看到下次执行时间

### 命令行执行

也可以直接通过命令行执行测试：

```bash
# 激活虚拟环境
# Windows
.\venv\Scripts\Activate.ps1
# macOS/Linux
source venv/bin/activate

# 执行测试
pytest

# 指定测试用例
pytest tests/test_cases_short/test_example.py

# 生成 Allure 报告
allure serve reports/allure-results
```

## 每日统计数据

系统自动维护 `daily_statistics.db` 数据库（位于项目根目录），记录每日统计汇总数据。

### 数据字段

| 字段 | 说明 |
|------|------|
| `date` | 日期（YYYY-MM-DD） |
| `online_rate` | 台架在线率（%） |
| `test_occupancy_rate` | 测试占用率（%） |
| `passed` | 通过用例数 |
| `failed` | 失败用例数 |
| `total` | 总用例数（passed + failed） |

### 数据来源

数据从 `status_history.db` 聚合计算得出，基于每日维度的统计。

### 同步机制

| 触发时机 | 说明 |
|----------|------|
| 服务启动 | 自动同步最近 30 天数据 |
| 每天 8:00、16:00 | 定时任务自动同步 |
| 手动触发 | 调用 `POST /api/statistics/daily-statistics/sync` |

### 更新逻辑

- 计算结果中存在且数据库中已存在的日期：**更新**
- 计算结果中不存在但数据库中存在的日期：**不变**
- 计算结果中存在但数据库中不存在的日期：**新增**

## 项目结构

```
hil-auto-test-1/
├── api/                          # 远程 API 封装
│   ├── api_generatePdf.py        # PDF 报告生成 API
│   └── api_readStatus.py         # 状态读取与上传 API
├── logs/                         # 日志目录
├── reports/                      # 测试报告目录
│   ├── allure-results/           # Allure 原始结果
│   ├── allure-report/            # Allure HTML 报告
│   ├── status_history.db         # 状态历史数据库
│   ├── test_procedure.json       # 测试执行过程
│   └── test_summary.json         # 测试汇总
├── resource/                     # 资源文件
│   ├── custom_favicon.png        # 自定义图标
│   ├── logo.jpg                  # Logo 图片
│   └── *.ttf                     # 字体文件
├── server/                       # Web 服务
│   ├── backend/                  # FastAPI 后端
│   │   ├── api/                  # API 路由
│   │   │   ├── allure_report.py  # 报告 API
│   │   │   ├── daily_statistics.py  # 每日统计 API
│   │   │   ├── pytest_config.py  # 配置 API
│   │   │   └── test_runner.py    # 测试执行 API
│   │   └── main.py               # 应用入口
│   └── frontend/                 # Vue 3 前端
│       ├── src/
│       │   ├── api/              # API 调用封装
│       │   ├── components/       # Vue 组件
│       │   │   ├── AllureReportViewer.vue  # 报告查看器
│       │   │   ├── HistoryChart.vue        # 历史状态图表
│       │   │   ├── PytestConfigEditor.vue  # 配置编辑器
│       │   │   ├── StatusChart.vue         # 实时状态图表
│       │   │   └── TestRunnerControl.vue   # 测试控制器
│       │   ├── router/           # 路由配置
│       │   ├── styles/           # 样式文件
│       │   ├── views/            # 页面视图
│       │   ├── App.vue           # 根组件
│       │   └── main.ts           # 入口文件
│       ├── index.html
│       ├── package.json
│       └── vite.config.ts
├── tests/                        # 测试用例
│   ├── test_cases/               # 标准测试用例
│   ├── test_cases_long/          # 长时测试用例
│   ├── test_cases_short/         # 短时测试用例
│   └── conftest.py               # pytest 配置和钩子
├── utils/                        # 工具模块
│   ├── allure_processor.py       # Allure 报告处理
│   ├── config.py                 # 配置读取
│   ├── constants.py              # 公共常量
│   ├── daily_statistics.py       # 每日统计
│   ├── logger.py                 # 日志配置
│   ├── progress_tracker.py       # 进度追踪
│   ├── rerun_handler.py          # 重试处理
│   ├── ssh_client.py             # SSH 客户端
│   └── status_recorder.py        # 状态记录
├── .env.example                  # 环境变量示例
├── .gitignore                    # Git 忽略配置
├── .pylintrc                     # Pylint 配置
├── pytest.ini                    # pytest 配置
├── requirements.txt              # Python 依赖
├── start_env.ps1                 # Windows 环境安装脚本
├── start_env.sh                  # Linux/macOS 环境安装脚本
├── start_server.ps1              # Windows 服务启动脚本
├── start_server.sh               # Linux/macOS 服务启动脚本
└── README.md                     # 项目文档
```

## 状态数据补全机制

系统通过 `status_history.db` 记录台架状态，快照间隔由 `.env` 中 `STATUS_SNAPSHOT_INTERVAL`（默认 10 秒）控制。当服务停机或出现异常间隔时，通过补全机制填充 `offline` 记录。

### 配置选项

| 环境变量 | 默认值 | 说明 |
|---------|---------|------|
| `STATUS_SNAPSHOT_INTERVAL` | 10 | 快照间隔秒数（运行中每隔N秒记录一次状态） |
| `STATUS_CHECK_DAYS` | 30 | 补全检查天数（服务启动时检查最近N天的记录） |
| `STATUS_RETENTION_DAYS` | 60 | 数据保留总天数（超过此天数会清理旧记录） |
| `STATUS_DELETE_DAYS` | 15 | 超过保留期限时删除的天数 |

### 服务启动时补全（`status_recorder.py`）

服务每次启动时，`_backfill_offline_records()` 执行两类补全：

| 类型 | 触发条件 | 说明 |
|------|----------|------|
| 中间间隔补全 | 相邻两条记录间隔 > 2× 快照间隔 | 扫描最近 30 天的记录，补全中间空隙 |
| 末尾间隔补全 | 最后一条记录距当前时间 > 2× 快照间隔 | 补全停机期间到当前时间的空隙 |

### 运行期间补全（`status_recorder.py`）

`_backfill_gap_during_runtime()` 在监控循环中执行，仅在测试 running 时检测：

| 类型 | 触发条件 | 说明 |
|------|----------|------|
| 中间间隔补全 | 最新记录距当前时间 > 2× 快照间隔 | 应对系统休眠、事件循环阻塞等异常 |

### 上传时补全（`api_readStatus.py`）

远程上传截取数据时，`_backfill_offline()` 只执行末尾补全：

| 类型 | 触发条件 | 说明 |
|------|----------|------|
| 末尾间隔补全 | 最后一条记录距当前时间 > 2× 快照间隔 | 中间空隙已在启动时补全，此处只补末尾 |

### 性能优化

为避免处理大量历史数据导致启动缓慢，系统做了以下优化：

1. **时间范围限制**：启动时只检查最近 30 天的记录
2. **自动清理**：当数据总时长超过 60 天时，自动删除最远的 15 天记录
3. **索引优化**：使用时间戳索引加速查询
4. **批量处理**：批量插入补全记录，减少数据库操作

这些优化确保了补全机制的高效运行，同时保持了数据的完整性和连续性。

### 补全逻辑汇总

```
服务启动 → 补中间间隔 + 补末尾间隔（写入本地 DB）
运行期间 → 仅检测最新记录间隔（仅 running 时）
上传截取 → 仅补末尾间隔（写入临时 DB）
```

所有补全记录的 `status` 为 `offline`，`record_type` 为 `snapshot`，按快照间隔逐条插入。

### 台架在线率与测试占用率

状态监控页面通过两个仪表盘展示指标，基于当前时间窗口内的记录点数计算：

| 指标 | 计算公式 | 在线状态 | 离线状态 |
|------|----------|----------|----------|
| 台架在线率 | `在线点数 / 总点数 × 100%` | `start`、`running`、`completed`、`idle`、`stopped` | `offline` |
| 测试占用率 | `占用点数 / 总点数 × 100%` | `start`、`running`、`completed`、`stopped` | `idle`、`offline` |

- **总点数**：时间窗口内所有状态记录条数
- **在线点数**：排除 `offline` 以外的所有状态点数
- **占用点数**：排除 `idle` 和 `offline` 的状态点数（即与测试相关的状态）
- 结果保留一位小数，上限 100%

## 核心模块说明

### 后端模块

| 文件 | 说明 |
|------|------|
| `main.py` | FastAPI 应用入口，配置 CORS、路由、生命周期、定时任务 |
| `test_runner.py` | 测试执行管理，SSH 远程执行，进度同步 |
| `allure_report.py` | Allure 报告生成和 PDF 报告生成 |
| `pytest_config.py` | pytest.ini 配置读写 |
| `daily_statistics.py` | 每日统计数据聚合，UPSERT 存储 |

### 前端模块

| 文件 | 说明 |
|------|------|
| `TestRunnerControl.vue` | 测试执行控制，SSE 连接，循环测试 |
| `AllureReportViewer.vue` | 报告查看器，Allure 和 PDF 报告展示 |
| `StatusChart.vue` | 实时状态图表，仪表盘和折线图 |
| `HistoryChart.vue` | 历史状态图表，统计数据可视化 |
| `PytestConfigEditor.vue` | pytest 配置编辑器 |

### 工具模块

| 文件 | 说明 |
|------|------|
| `ssh_client.py` | SSH 客户端封装，远程命令执行 |
| `status_recorder.py` | 状态记录器，SQLite 存储，后台监控 |
| `progress_tracker.py` | 测试进度追踪，实时状态更新 |
| `allure_processor.py` | Allure 结果处理，JSON 数据提取 |
| `rerun_handler.py` | 失败重试元数据管理 |
| `daily_statistics.py` | 每日统计数据聚合和存储 |

## API 接口文档

### 测试执行 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/test/start` | 启动测试 |
| POST | `/api/test/stop` | 停止测试 |
| GET | `/api/test/status` | 获取测试状态 |
| GET | `/api/test/ssh-status` | 获取 SSH 连接状态 |
| GET | `/api/test/progress/stream` | SSE 进度流 |
| GET | `/api/test/progress` | 获取测试进度 |
| GET | `/api/test/status/history` | 查询状态历史记录 |

### 报告 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/allure/status` | 获取 Allure 报告状态 |
| POST | `/api/allure/generate` | 生成 Allure 报告 |
| GET | `/api/allure/diagnose` | 诊断报告生成问题 |
| POST | `/api/allure/generate-pdf` | 生成 PDF 报告 |
| GET | `/api/allure/pdf-status` | 获取 PDF 报告状态 |

### 配置 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/pytest/config` | 获取 pytest 配置 |
| POST | `/api/pytest/config` | 更新 pytest 配置 |
| POST | `/api/pytest/config/reset` | 重置 pytest 配置 |
| GET | `/api/pytest/test-dirs` | 获取测试目录列表 |

### 每日统计 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/statistics/daily-statistics` | 查询每日统计数据 |
| POST | `/api/statistics/daily-statistics/sync` | 同步每日统计数据 |

## 开发指南

### 本地开发环境搭建

```bash
# 1. 创建虚拟环境
python -m venv venv

# 2. 激活虚拟环境
# Windows
.\venv\Scripts\Activate.ps1
# macOS/Linux
source venv/bin/activate

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

# 4. 安装前端依赖
cd server/frontend
npm install
```

### 后端开发

```bash
# 启动后端开发服务器（带热重载）
cd server/backend
uvicorn main:app --reload --port 8000
```

### 前端开发

```bash
# 启动前端开发服务器
cd server/frontend
npm run dev

# 构建生产版本
npm run build
```

### 测试用例编写规范

```python
# tests/test_cases/test_example.py

import pytest

class TestExample:
    """示例测试类。"""

    def test_case_001(self):
        """测试用例 001：基本示例。"""
        assert 1 + 1 == 2

    @pytest.mark.smoke
    def test_case_002(self):
        """测试用例 002：冒烟测试。"""
        assert True
```

### 代码风格规范

- Python 代码遵循 PEP 8 规范
- 使用 Pylint 进行代码检查
- 注释使用中文，保持清晰易懂

## 常见问题 (FAQ)

### SSH 连接失败

**问题**：启动测试时提示 SSH 连接失败

**解决方案**：
1. 检查 `.env` 文件中的 SSH 配置是否正确
2. 确认远程主机 SSH 服务已启动
3. 检查网络连通性：`ping <SSH_HOST>`
4. 确认用户名密码正确

### 报告生成失败

**问题**：测试完成后报告未生成

**解决方案**：
1. 检查 `reports/` 目录权限
2. 确认 Allure 已正确安装
3. 查看后端日志排查错误

### 前端无法访问后端

**问题**：前端页面显示网络错误

**解决方案**：
1. 确认后端服务已启动（端口 8000）
2. 检查 CORS 配置是否正确
3. 确认前端 API 地址配置正确

### 循环测试不执行

**问题**：启用循环测试后没有自动执行下一轮

**解决方案**：
1. 检查循环间隔设置是否正确
2. 查看浏览器控制台是否有错误
3. 确认后端服务未重启

### PDF 报告显示空白

**问题**：PDF 报告页面空白或加载失败

**解决方案**：
1. 确认测试已完成并生成报告
2. 检查 `reports/test_summary.json` 是否存在
3. 刷新页面重试

## 更新日志

### v1.0.0

- 初始版本发布
- Web UI 管理界面
- SSH 远程测试执行
- 循环测试模式
- Allure 和 PDF 报告生成
- 实时状态监控

## 许可证

MIT License