SimpleRemoter/docs/TestPlan.md

SimpleRemoter 测试计划

本文档定义了项目的测试策略、优先级和实施路线图。

测试目标

1. 发现潜在隐患 - 边界条件、异常情况、内存问题
2. 回归保护 - 确保修改不引入新 bug
3. 提升代码质量 - 通过测试驱动改进代码

模块概览

代码复杂度分析

模块	客户端文件	服务端文件	LOC	复杂度
网络核心	IOCPClient.cpp	IOCPServer.cpp	1500+	高
文件传输	FileManager.cpp	FileManagerDlg.cpp	4400+	高
远程桌面	ScreenManager.cpp	ScreenSpyDlg.cpp	4700+	高
缓冲区	Buffer.cpp	Buffer.cpp	500+	中 ✅ 已测试
系统管理	SystemManager.cpp	SystemDlg.cpp	800+	中
终端	ShellManager/ConPTY	ShellDlg/TerminalDlg	600+	中
注册表	RegisterManager.cpp	RegisterDlg.cpp	400+	低
服务管理	ServicesManager.cpp	ServicesDlg.cpp	400+	低

协议数据结构

结构体	文件	大小	用途
FileChunkPacket	file_upload.h	41B	V1 文件传输
FileChunkPacketV2	file_upload.h	77B	V2 文件传输
FileResumePacketV2	file_upload.h	49B+	断点续传
FileCompletePacketV2	file_upload.h	69B	完成校验
C2CPreparePacket	file_upload.h	17B	C2C 准备
HeaderFlag	header.h	-	包头标识
ZstaHeader	ZstdArchive.h	-	压缩头

测试优先级

P0 - 关键（必须测试）

这些是系统核心，问题会导致功能完全失效：

模块	测试类型	测试重点	用例数	状态
Buffer	单元测试	读写、边界、下溢	73	✅ 完成
协议编解码	单元测试	数据包序列化/反序列化	58	✅ 完成
协议头验证	单元测试	包头加密/解密/版本	29	✅ 完成
路径处理	单元测试	路径拼接、相对路径、特殊字符	包含在协议测试	✅ 完成

P1 - 高优先级

核心功能，问题会严重影响用户体验：

模块	测试类型	测试重点	用例数	状态
文件传输逻辑	单元测试	V2协议、分块、传输选项	37	✅ 完成
分块管理	单元测试	范围管理、合并、缺失检测	36	✅ 完成
SHA-256 校验	单元测试	流式哈希、完整性验证	28	✅ 完成
断点续传	单元测试	状态序列化、恢复逻辑	26	✅ 完成
粘包/分包	单元测试	数据包边界处理	24	✅ 完成
HTTP 伪装	单元测试	协议伪装/解除	27	✅ 完成
屏幕捕获	单元测试	图像压缩、差分算法	425	✅ 完成

P2 - 中优先级

重要功能，但问题影响范围有限：

模块	测试类型	测试重点	预计用例
系统管理	单元测试	进程列表解析	20+
终端	单元测试	命令解析、输出处理	15+
压缩模块	单元测试	zstd 压缩/解压	15+

P3 - 低优先级

辅助功能，可延后测试：

模块	测试类型	测试重点	预计用例
注册表	单元测试	路径解析	10+
服务管理	单元测试	状态解析	10+
音视频	集成测试	数据流	10+

实施路线图

Phase 1: 协议层测试 ✅ 已完成

目标： 测试所有数据包的序列化/反序列化

状态： 131 个测试全部通过

test/
└── unit/
    ├── client/
    │   └── BufferTest.cpp           # 客户端 Buffer (33 用例) ✅
    ├── server/
    │   └── BufferTest.cpp           # 服务端 Buffer (40 用例) ✅
    └── protocol/
        ├── PacketTest.cpp           # 文件传输包、命令解析 (39 用例) ✅
        └── PathUtilsTest.cpp        # 路径处理工具 (19 用例) ✅

发现并修复的问题：

• Buffer ULONG 下溢漏洞：当 Skip(len) 中 len > m_nDataLength 时导致下溢

测试覆盖：

• V2 文件传输包结构 (FileChunkPacketV2, FileResumePacketV2 等)
• 路径处理工具 (相对路径、特殊字符、边界条件)
• Buffer 读写操作、边界处理、线程安全

Phase 2: 文件传输测试 ✅ 已完成

目标： 确保文件传输逻辑正确

状态： 127 个测试全部通过

test/
└── unit/
    └── file/
        ├── FileTransferV2Test.cpp       # V2 传输逻辑 (37 用例) ✅
        ├── ChunkManagerTest.cpp         # 分块管理 (36 用例) ✅
        ├── SHA256VerifyTest.cpp         # 文件校验 (28 用例) ✅
        └── ResumeStateTest.cpp          # 断点续传状态 (26 用例) ✅

测试覆盖：

类别	测试内容	用例数
V2 传输选项	FFV2_* 标志组合、TransferID 生成	12
数据包构建	FileChunkPacketV2、FileQueryResumeV2 等	25
范围管理	添加、合并、缺失检测、边界条件	36
SHA-256	流式计算、空数据、大数据、已知向量	28
断点续传	状态序列化/反序列化、恢复请求/响应	26

关键发现：

• 测试使用独立实现验证协议设计正确性
• RangeManager 相邻范围自动合并 (0-100 + 100-200 → 0-200)

Phase 3: 网络通信测试 ✅ 已完成

目标： 验证网络层协议处理的正确性

状态： 80 个测试全部通过

test/
└── unit/
    └── network/
        ├── HeaderTest.cpp               # 协议头验证 (29 用例) ✅
        ├── PacketFragmentTest.cpp       # 粘包/分包处理 (24 用例) ✅
        └── HttpMaskTest.cpp             # HTTP 伪装 (27 用例) ✅

测试覆盖：

类别	测试内容	用例数
协议头	FLAG 生成、加密/解密、多版本验证	29
粘包/分包	完整包、分片、多包粘连、边界条件	24
HTTP 伪装	GET/POST 伪装、解除、边界检测	27

协议细节验证：

• 包头结构: FLAG(8B) + PackedLen(4B) + OrigLen(4B) = 16 bytes
• 位置相关 XOR 加密 (key ^ (i * 31))
• 支持 HeaderEncV0-V6 多版本兼容

Phase 4: 图像处理测试 ✅ 已完成

目标： 验证屏幕捕获和压缩算法

状态： 425 个测试全部通过

test/
└── unit/
    └── screen/
        ├── DiffAlgorithmTest.cpp        # 差分算法 (32 用例) ✅
        ├── RGB565Test.cpp               # RGB565 压缩 (286 用例) ✅
        ├── ScrollDetectorTest.cpp       # 滚动检测 (43 用例) ✅
        └── QualityAdaptiveTest.cpp      # 质量自适应 (64 用例) ✅

测试覆盖：

类别	测试内容	用例数
差分算法	帧比较、差分编码/解码、SSE2 优化验证	32
RGB565	BGRA↔RGB565 转换、量化误差、批量处理	286
滚动检测	CRC32 行哈希、垂直滚动检测、边缘区域	43
质量自适应	RTT→等级映射、防抖逻辑、冷却时间	64

关键实现细节：

• RGB565 量化误差: 5-bit 最大误差 7，6-bit 最大误差 3
• 滚动检测: MIN_SCROLL_LINES=16, MATCH_THRESHOLD=85%
• 质量自适应: 降级 2 次稳定，升级 5 次稳定，分辨率变化冷却 30 秒

Phase 5: 其他模块 (按需)

根据实际情况逐步扩展测试覆盖。

测试基础设施

目录结构

test/
├── CMakeLists.txt              # 构建配置
├── test.bat                    # Windows 测试脚本
├── unit/                       # 单元测试
│   ├── client/                 # 客户端测试
│   │   └── BufferTest.cpp      # ✅ 已完成
│   ├── server/                 # 服务端测试
│   │   └── BufferTest.cpp      # ✅ 已完成
│   ├── protocol/               # 协议测试 (Phase 1)
│   ├── file/                   # 文件传输测试 (Phase 2)
│   └── screen/                 # 屏幕测试 (Phase 4)
├── integration/                # 集成测试
│   └── network/                # 网络测试 (Phase 3)
├── fixtures/                   # 测试数据
│   ├── images/                 # 测试图像
│   └── files/                  # 测试文件
└── mocks/                      # Mock 对象
    └── MockSocket.h

测试工具函数

需要创建的辅助函数：

// test/TestUtils.h

// 创建临时测试目录
std::wstring CreateTempTestDir();

// 创建测试文件
void CreateTestFile(const std::wstring& path, size_t size);

// 比较文件内容
bool CompareFiles(const std::wstring& file1, const std::wstring& file2);

// 加载测试图像
std::vector<BYTE> LoadTestImage(const std::string& name);

// 模拟网络延迟
void SimulateNetworkDelay(int ms);

代码覆盖率目标

阶段	覆盖率目标	说明
Phase 1	90%+	协议层应接近完全覆盖
Phase 2	80%+	文件传输核心逻辑
Phase 3	70%+	网络层关键路径
Phase 4	60%+	图像处理算法

持续集成

建议在 GitHub Actions 中自动运行测试：

name: Unit Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: windows-latest
    steps:
    - uses: actions/checkout@v4
    - name: Build and Test
      run: |
        cd test
        test.bat rebuild
        test.bat run

当前进度

总计: 763 个测试用例，全部通过 ✅

阶段	模块	用例数	状态
Phase 1	Buffer (客户端+服务端)	73	✅
Phase 1	协议层 (Packet + PathUtils)	58	✅
Phase 2	文件传输	127	✅
Phase 3	网络通信	80	✅
Phase 4	图像处理	425	✅
合计		763	✅

下一步行动

1. Phase 5: 其他模块 (按需)

   • 系统管理模块测试
   • 终端模块测试
   • 压缩模块测试

2. 可选扩展

   • 集成测试
   • 持续集成配置

附录：已发现并修复的问题

日期	阶段	模块	问题	修复
2026-03-08	Phase 1	Buffer	ULONG 下溢：Skip(len) 当 len > m_nDataLength 导致下溢	添加防护检查

测试设计说明：

• Phase 2-3 测试使用独立实现（测试副本）验证协议设计
• 这种方式验证的是协议规范正确性，而非生产代码 bug
• 发现的测试问题：RangeManagerTest.MergeOutOfOrder 预期修正（相邻范围自动合并）

---

文档版本: 2.0 最后更新: 2026-03-08