suyu_two/docs/测试约定.md

测试约定

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

测试范围

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

不使用自动化测试验证界面布局、视觉效果和真实鼠标操作，这些内容由交付前人工验收确认。跨运行模式的 Qt 排队信号无法只靠服务测试证明，因此保留一个无界面运行的控制器测试，专门验证退出离线仿真后不会恢复旧梯形图轨迹；PLC 自动搜索还保留一个离屏对话框流程测试，验证开始、取消、进度和找到后自动提交参数。

功能自动化测试

测试目标	主要契约
domain_tests	地址、模型、数量边界、Float32 编解码和运行前校验
application_settings_tests	默认配置创建、严格 INI 校验、缺失与未知字段、版本和整份回退
alarm_service_tests	报警定义和运行记录生命周期
hmi_editor_service_tests	HMI 编辑、原子删除、历史、导航和 Float32 数值控件读写
logic_editor_service_tests	结构化梯形图编辑、归一化和历史
offline_simulation_service_tests	梯形图扫描语义、离线初始 M/D 快照、真机缓存副本推算、只读隔离、跨扫描状态和故障处理
project_management_tests	JSON 往返、非法文件和工程保存状态
register_monitor_service_tests	监视地址、Int16/Float32 读写、离线初始值捕获、批量步长、重叠提示和活动仓库
runtime_mode_service_tests	编辑、离线、真机只读轨迹和仓库切换
runtime_panel_controller_tests	本地扫描排队回调和编辑态轨迹清理
plc_connection_dialog_tests	PLC 端口刷新及自动搜索开始、取消、进度和参数回填
plc_runtime_tests	PLC 缓存、完整轮询通知、成对轮询边界、错误恢复和 Fake gateway

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

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

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

功能测试统一运行：

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

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

性能测试

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

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

运行方式：

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

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

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

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

Float32 真机验收还要确认：写入一次发送两个连续保持寄存器，轮询读回后界面才刷新；测试结束恢复 D 起始字和下一个 D 的原值并再次读回确认。