# 测试约定

本项目已经进入交付整理阶段，测试只保留能直接证明交付质量的三类内容：功能自动化测试、性能测试和真实 PLC 实测。测试数量不是质量指标，不重复验证同一个业务结论。

## 测试范围

| 类型 | 证明内容 | 执行方式 |
| --- | --- | --- |
| 功能自动化测试 | 领域规则、服务用例、JSON 工程、离线执行、运行面板时序和 Fake PLC 状态机正确 | 提交前自动执行 |
| 性能测试 | 代表性工程扫描和边界规模寄存器访问性能 | 独立执行 |
| 真实 PLC 实测 | 串口、Modbus RTU、PLC 响应、接线和现场联动有效 | 人工执行并记录 |

自动化测试验证画布命中、拖动选择、对象与整行剪贴板、连续光标和轨迹字段到图元的投影，不以像素截图代替人工视觉验收；符号比例、颜色观感和不同系统缩放仍由交付前人工检查。跨运行模式的 Qt 排队信号无法只靠服务测试证明，因此保留离屏控制器测试验证退出离线仿真后不会恢复旧梯形图轨迹；PLC 自动搜索还保留离屏对话框流程测试，验证开始、取消、进度和找到后自动提交参数。

## 功能自动化测试

| 测试目标 | 主要契约 |
| --- | --- |
| `domain_tests` | 地址、模型、数量边界、Int16/Int32/Float32/Float64 编解码和带竖线并联的输出路径可达性校验 |
| `application_settings_tests` | 默认配置创建、严格 INI 校验、缺失与未知字段、版本和整份回退 |
| `alarm_service_tests` | 报警定义和运行记录生命周期 |
| `hmi_editor_service_tests` | HMI 编辑、原子删除、历史、导航和四种 D 数值控件读写 |
| `logic_editor_service_tests` | 连续网格编辑、网络注释首行归属与合并冲突、输出自动补尾线、网格与整行片段复制粘贴、冲突回滚和历史 |
| `offline_simulation_service_tests` | 梯形图扫描语义、离线初始 M/D 快照、真机缓存副本推算、只读隔离、跨扫描状态和故障处理 |
| `project_management_tests` | JSON 往返、支路隐藏注释等非法文件和工程保存状态 |
| `register_monitor_service_tests` | 监视地址、四种 D 类型读写、离线初始值捕获、批量步长、重叠提示和活动仓库 |
| `runtime_project_bundle_tests` | 用户运行程序封装的写入、读取、校验和损坏拒绝 |
| `runtime_mode_service_tests` | 编辑、离线、真机只读轨迹、仓库切换和断路工程启动拦截 |
| `runtime_panel_controller_tests` | 完整执行器快照经过控制器和运行窗口后的轨迹投影、排队回调、画布框选、对象/行号剪贴板和连续输入 |
| `plc_connection_dialog_tests` | PLC 端口刷新及自动搜索开始、取消、进度和参数回填 |
| `plc_runtime_tests` | PLC 缓存、完整轮询通知、多字范围拆块、一次多寄存器写入、错误恢复和 Fake gateway |

同一规则只在成本最低、失败定位最清楚的层验证：

- Domain 验证数据和模型是否合法
- Service 验证一次业务操作如何改变模型、历史或寄存器
- JSON 验证工程文件能否严格保存、加载和拒绝非法内容
- Fake PLC 验证无需真实设备即可重复执行的缓存、首读、超时、断线和恢复逻辑

如果两个测试的输入、执行路径和断言相同，只保留更低层的一个。一个测试函数只验证一个行为主题，多个上下界属于同一业务规则时可以放在一起。

功能测试统一运行：

```powershell
pwsh -NoLogo -NoProfile -File .\scripts\run_qt_tests.ps1 -Configuration Release
```

`app/tests/tests.pro` 只聚合上述 13 个功能测试目标。测试构建输出放在 `build/`，不写入 `app/`。

## 性能测试

性能测试不混入普通功能回归，当前独立目标为 `performance_tests`：

- 100 个控制逻辑的一次软件扫描
- 4001 个 M 寄存器的一次完整写入和读取遍历

运行方式：

```powershell
pwsh -NoLogo -NoProfile -File .\scripts\run_qt_tests.ps1 -Configuration Release -Suite Performance
```

性能基准使用固定规模和 `QBENCHMARK`，不设置容易受机器差异影响的脆弱毫秒阈值。结果用于记录当前交付版本基线，不替代功能断言。

需要连续执行功能和性能测试时使用：

```powershell
pwsh -NoLogo -NoProfile -File .\scripts\run_qt_tests.ps1 -Configuration Release -Suite All
```

## 真实 PLC 实测

真实 PLC 测试不写入自动化测试代码，也不进入 `tests.pro`。Fake PLC 测试只能证明软件状态机，不能代替串口、设备、接线和现场负载验证。

标准安全验证使用 `COM3 / 9600 / 8E1 / 站号 1` 或现场批准配置，并记录：

1. PLC 的 STOP/RUN 状态、串口参数、接线和现场负载条件
2. 写入前读取的原值
3. 临时写入值及 PLC 读回结果
4. 恢复原值及再次读回结果
5. 是否涉及 PLC 内部程序和现场动作

安全通信验证先在 STOP 状态读原值，测试后恢复并再次读回。未经确认接线、地址和负载，不执行 RUN 联动。本项目不生成、下载或修改 PLC 程序。

当前已完成的真机证据：

- `COM3 / 9600 / 8E1 / 站号 1` 下读取 `D4000=0`，临时写入并读回 `1`，恢复并读回 `0`
- 使用 `json/motor_forward_reverse.json` 完成 RUN 联动，正转启动、反转启动、停止和状态反馈正常

## 提交前检查

1. 运行 13 个 Release 功能测试目标
2. 单独运行 `performance_tests` 并保留基准输出
3. 构建 Qt Release 主程序
4. 按风险决定是否重新执行真实 PLC 实测；未重测时引用已有验收记录并说明原因
5. 运行 `git diff --check`

多字类型真机验收还要确认：Int32/Float32 一次发送两个连续保持寄存器，Double 一次发送四个连续保持寄存器，轮询读回后界面才刷新；测试结束恢复全部占用 D 的原值并再次读回确认。