Pelco KBD300A 模拟器:18. 按依赖顺序 + 复杂度由低到高逐步推进pytest单元测试

第 18 篇：按依赖顺序 + 复杂度由低到高逐步推进pytest单元测试**

我们采用"依赖顺序 + 复杂度由低到高"的策略组织单元测试，确保底层模块先通过测试，上层模块再依赖可靠的基础。测试优先覆盖纯函数、无外部依赖的模块，再逐步扩展到涉及线程、信号、文件 I/O、模拟器等复杂模块。

测试模块顺序（依赖与复杂度递增）

1. core/protocol/pelco_protocol.py ------ 最基础纯函数，无外部依赖
2. core/macro/standard.py ------ CommandValidator、范围校验
3. core/alarm/rules.py ------ load/save/execute
4. core/macro/parser.py ------ lexer/parser
5. core/template/renderer.py ------ 模板渲染
6. core/utils/log_emitter.py ------ 信号、缓冲区
7. core/macro/commands.py ------ 命令执行核心
8. core/macro/engine.py ------ 宏执行引擎
9. core/serial/protocol.py ------ 帧提取与解析
10. core/serial/manager.py + worker.py ------ 串口管理与线程
11. core/template/library.py ------ 模板文件管理
12. core/simulator/virtual_device.py ------ 模拟器状态机

18.1 core/protocol/pelco_protocol.py 单元测试

测试文件 ：tests/unit/test_pelco_protocol.py
覆盖要点：

• build_pelco_d / build_pelco_p（不同参数组合）
• parse_pelco_packet（D/P 协议自动识别、PTZ、预置位、AUX、校验和错误、未知命令）
• 9 字节变体兼容性（若启用）
• 边界值与非法帧处理

运行命令：

pytest tests/unit/test_pelco_protocol.py -v --tb=short

预期：所有测试用例通过，显示具体参数化测试名称及 PASS。

18.2 core/macro/standard.py 单元测试

测试文件 ：tests/unit/test_standard.py
覆盖要点：

• 常量、枚举完整性
• COMMAND_SPECS 结构校验
• validate_command：正常、未知命令、参数数量/类型/范围错误（E001~E004）
• 可选参数处理（cam_id 默认值）
• 静态方法：get_command_spec、list_all_commands、get_commands_by_category
• 边界值（speed ±100、preset 1~255、aux 1~8）

运行命令：

pytest tests/unit/test_standard.py -v --tb=short

预期：约 20+ 个测试全部通过。

18.3 core/alarm/rules.py 单元测试

测试文件 ：tests/unit/test_alarm_rules.py
覆盖要点：

• load_alarm_rules / save_alarm_rules（文件读写、空文件、异常处理）
• execute_alarm_action（不同 action 类型：run_macro、load_template、notify、ack 等）
• 规则过滤（enabled、alarm_code 匹配）
• 最后触发时间更新

运行命令：

pytest tests/unit/test_alarm_rules.py -v --tb=short

预期：全部通过（含 mock 文件 I/O 和动作执行）。

18.4 core/macro/parser.py 单元测试

测试文件 ：tests/unit/test_parser.py
覆盖要点：

• Lexer：token 识别（数字、ID、字符串、注释、符号）
• Parser：简单命令、字符串、变量、loop、for、if/else、嵌套结构
• 语法错误恢复（不崩溃，返回部分 AST）
• 位置信息（line/column）准确性

运行命令：

pytest tests/unit/test_parser.py -v --tb=short

18.5 core/template/renderer.py 单元测试

测试文件 ：tests/unit/test_renderer.py
覆盖要点：

• {{{name}}} → 原始值替换
• {{name}} → 类型转换（int/float → 数字字符串、bool → "true"/"false"、str → 加引号）
• 缺少参数 → ValueError + 日志
• 空参数字典 → 返回原始脚本

运行命令：

pytest tests/unit/test_renderer.py -v --tb=short

18.6 core/utils/log_emitter.py 单元测试

测试文件 ：tests/unit/test_log_emitter.py
覆盖要点：

• 单例模式（get_log_emitter 返回同一实例）
• 各日志方法（info、warning、error、send、receive、simulator、alarm）信号发射
• 缓冲区机制（use_buffer=True 时进入缓冲，flush 后触发 logs_batch）
• error 触发 error_occurred 信号
• 非法日志类型自动转为 info

运行命令：

pytest tests/unit/test_log_emitter.py -v --tb=short

18.7 core/macro/commands.py 单元测试

测试文件 ：tests/unit/test_commands.py
覆盖要点：

• 各 cmd_xxx 方法（ptz_control、zoom、focus、iris、preset、aux、pattern 等）
• 参数验证（CommandValidator）
• 默认 cam_id 处理
• 执行日志记录
• 异常情况（未知命令、无效参数）

运行命令：

pytest tests/unit/test_commands.py -v --cov=core/macro/commands --cov-report=term-missing

18.8 core/macro/engine.py 单元测试

测试文件 ：tests/unit/test_macro_engine.py
覆盖要点：

• 生命周期（init、set_script、run、stop、pause/resume）
• AST 执行（命令、loop、for、if）
• 信号（started、stopped、error、progress、command_executed）
• 进度计算、检查点、缓存
• 异常安全与日志

运行命令：

pytest tests/unit/test_macro_engine.py -v --tb=short

18.9 core/serial/protocol.py 单元测试

测试文件 ：tests/unit/test_serial_protocol.py
覆盖要点：

• detect_protocol（D/P/未知）
• extract_frame（完整帧、不完整、校验失败）
• parse_frame（PTZ、zoom、preset、query、错误帧、Pelco-P 未知命令）
• 校验和验证

运行命令：

pytest tests/unit/test_serial_protocol.py -v --tb=short

18.10 core/serial/manager.py + worker.py 单元测试

测试文件 ：tests/unit/test_serial_manager_worker.py
覆盖要点：

• open/close/write/is_open
• 信号转发（opened、closed、error、data_received、parsed_received）
• 默认 cam_id 同步到控制方法

运行命令：

pytest tests/unit/test_serial_manager_worker.py -v --tb=short

18.11 core/template/library.py 单元测试

测试文件 ：tests/unit/test_template_library.py
覆盖要点：

• load/save（JSON 读写、异常处理）
• find（存在/不存在）
• _validate_template（合法/非法结构）
• _create_default_templates
• 缓存机制（首次加载后复用）

运行命令：

pytest tests/unit/test_template_library.py -v --tb=short

18.12 core/simulator/virtual_device.py 单元测试

测试文件 ：tests/unit/test_virtual_device.py
覆盖要点：

• process_command（ACK、查询响应、错误响应）
• update_from_command（PTZ、zoom、focus、iris、aux）
• generate_response（各查询类型）
• 状态范围限制（pan/tilt/zoom）

运行命令：

pytest tests/unit/test_virtual_device.py -v --tb=short

测试执行建议

• 按顺序运行上述测试文件，确保底层模块先通过。
• 使用 --cov 生成覆盖率报告，关注未覆盖分支。
• 所有测试均使用 mock 避免真实串口/文件依赖，保证快速稳定。
• 通过后可继续集成测试（serial + protocol + macro）。

下一阶段：完成以上单元测试后，我们进入集成测试阶段。

👉上一篇 ：按照pytest自动化测试方案规划建立测试基础框架
👉总目录：Python开发软键盘全程总览

👉下一篇