Init: Migrate SimpleRemoter (Since v1.3.1) to Gitea
This commit is contained in:
yuanyuanxiang
439
docs/TestingArchitecture.md
Normal file
439
docs/TestingArchitecture.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# SimpleRemoter 测试架构
|
||||
|
||||
本文档描述项目的测试架构、框架选择和最佳实践。
|
||||
|
||||
## 目录
|
||||
|
||||
- [测试框架](#测试框架)
|
||||
- [目录结构](#目录结构)
|
||||
- [测试分类](#测试分类)
|
||||
- [命名规范](#命名规范)
|
||||
- [编写指南](#编写指南)
|
||||
- [运行测试](#运行测试)
|
||||
- [CI/CD 集成](#cicd-集成)
|
||||
|
||||
## 测试框架
|
||||
|
||||
### Google Test (gtest)
|
||||
|
||||
项目采用 [Google Test](https://github.com/google/googletest) 作为主要测试框架。
|
||||
|
||||
**选择理由：**
|
||||
|
||||
| 特性 | 说明 |
|
||||
|------|------|
|
||||
| 功能完整 | 支持断言、Mock、参数化测试、死亡测试 |
|
||||
| 跨平台 | Windows/Linux 均可使用 |
|
||||
| VS 集成 | Visual Studio Test Explorer 直接支持 |
|
||||
| CI 友好 | 输出 JUnit XML 格式，CI 系统可直接解析 |
|
||||
| 社区活跃 | 文档完善，问题易解决 |
|
||||
|
||||
### 版本要求
|
||||
|
||||
- Google Test: 1.14.0+
|
||||
- CMake: 3.14+
|
||||
- C++: 17+ (使用结构化绑定等特性)
|
||||
- Visual Studio: 2019 或 2022
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
SimpleRemoter/
|
||||
├── test/ # 测试根目录
|
||||
│ ├── CMakeLists.txt # 测试构建配置 (14 个测试可执行文件)
|
||||
│ ├── test.bat # Windows 测试管理脚本
|
||||
│ ├── unit/ # 单元测试
|
||||
│ │ ├── client/ # 客户端模块测试
|
||||
│ │ │ └── BufferTest.cpp # 客户端 Buffer (33 用例) ✅
|
||||
│ │ ├── server/ # 服务端模块测试
|
||||
│ │ │ └── BufferTest.cpp # 服务端 Buffer (40 用例) ✅
|
||||
│ │ ├── protocol/ # 协议层测试 (Phase 1)
|
||||
│ │ │ ├── PacketTest.cpp # 文件传输包 (39 用例) ✅
|
||||
│ │ │ └── PathUtilsTest.cpp # 路径处理 (19 用例) ✅
|
||||
│ │ ├── file/ # 文件传输测试 (Phase 2)
|
||||
│ │ │ ├── FileTransferV2Test.cpp # V2 传输逻辑 (37 用例) ✅
|
||||
│ │ │ ├── ChunkManagerTest.cpp # 分块管理 (36 用例) ✅
|
||||
│ │ │ ├── SHA256VerifyTest.cpp # SHA-256 校验 (28 用例) ✅
|
||||
│ │ │ └── ResumeStateTest.cpp # 断点续传状态 (26 用例) ✅
|
||||
│ │ ├── network/ # 网络通信测试 (Phase 3)
|
||||
│ │ │ ├── HeaderTest.cpp # 协议头验证 (29 用例) ✅
|
||||
│ │ │ ├── PacketFragmentTest.cpp # 粘包/分包 (24 用例) ✅
|
||||
│ │ │ └── HttpMaskTest.cpp # HTTP 伪装 (27 用例) ✅
|
||||
│ │ └── screen/ # 图像处理测试 (Phase 4)
|
||||
│ │ ├── DiffAlgorithmTest.cpp # 差分算法 (32 用例) ✅
|
||||
│ │ ├── RGB565Test.cpp # RGB565 压缩 (286 用例) ✅
|
||||
│ │ ├── ScrollDetectorTest.cpp # 滚动检测 (43 用例) ✅
|
||||
│ │ └── QualityAdaptiveTest.cpp # 质量自适应 (64 用例) ✅
|
||||
│ ├── integration/ # 集成测试 (待实现)
|
||||
│ ├── mocks/ # Mock 对象 (待实现)
|
||||
│ └── fixtures/ # 测试数据/夹具 (待实现)
|
||||
├── docs/
|
||||
│ └── TestingArchitecture.md # 本文档
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 测试分类
|
||||
|
||||
### 单元测试 (Unit Tests)
|
||||
|
||||
测试单个类或函数的独立功能。
|
||||
|
||||
**特点：**
|
||||
- 快速执行（毫秒级）
|
||||
- 无外部依赖（网络、文件系统等）
|
||||
- 高覆盖率目标（>80%）
|
||||
|
||||
**示例：**
|
||||
```cpp
|
||||
TEST(BufferTest, WriteBuffer_ValidData_ReturnsTrue) {
|
||||
CBuffer buffer;
|
||||
BYTE data[] = {1, 2, 3};
|
||||
EXPECT_TRUE(buffer.WriteBuffer(data, 3));
|
||||
EXPECT_EQ(buffer.GetBufferLength(), 3);
|
||||
}
|
||||
```
|
||||
|
||||
### 集成测试 (Integration Tests)
|
||||
|
||||
测试多个组件的协作。
|
||||
|
||||
**特点：**
|
||||
- 测试组件间交互
|
||||
- 可能涉及真实资源
|
||||
- 执行时间较长
|
||||
|
||||
### 端到端测试 (E2E Tests)
|
||||
|
||||
测试完整的用户场景。
|
||||
|
||||
**特点：**
|
||||
- 模拟真实使用场景
|
||||
- 客户端 ↔ 服务端完整流程
|
||||
- 执行时间最长
|
||||
|
||||
## 命名规范
|
||||
|
||||
### 测试文件
|
||||
|
||||
```
|
||||
<ClassName>Test.cpp
|
||||
例：BufferTest.cpp, FileManagerTest.cpp
|
||||
```
|
||||
|
||||
### 测试套件
|
||||
|
||||
```
|
||||
<ClassName>Test
|
||||
例：TEST(BufferTest, ...)
|
||||
```
|
||||
|
||||
### 测试用例
|
||||
|
||||
采用 `MethodName_StateUnderTest_ExpectedBehavior` 格式：
|
||||
|
||||
```cpp
|
||||
// 好的命名
|
||||
TEST(BufferTest, ReadBuffer_WhenBufferEmpty_ReturnsZero)
|
||||
TEST(BufferTest, WriteBuffer_ExceedsCapacity_ReallocatesMemory)
|
||||
TEST(BufferTest, Skip_ExceedsDataLength_ClampsToAvailable)
|
||||
|
||||
// 避免的命名
|
||||
TEST(BufferTest, Test1)
|
||||
TEST(BufferTest, ReadWorks)
|
||||
```
|
||||
|
||||
## 编写指南
|
||||
|
||||
### AAA 模式
|
||||
|
||||
所有测试应遵循 Arrange-Act-Assert 模式：
|
||||
|
||||
```cpp
|
||||
TEST(BufferTest, ReadBuffer_PartialRead_ReturnsRequestedLength) {
|
||||
// Arrange - 准备测试数据和对象
|
||||
CBuffer buffer;
|
||||
BYTE writeData[] = {1, 2, 3, 4, 5};
|
||||
buffer.WriteBuffer(writeData, 5);
|
||||
|
||||
// Act - 执行被测操作
|
||||
BYTE readData[3];
|
||||
ULONG bytesRead = buffer.ReadBuffer(readData, 3);
|
||||
|
||||
// Assert - 验证结果
|
||||
EXPECT_EQ(bytesRead, 3);
|
||||
EXPECT_EQ(readData[0], 1);
|
||||
EXPECT_EQ(readData[1], 2);
|
||||
EXPECT_EQ(readData[2], 3);
|
||||
EXPECT_EQ(buffer.GetBufferLength(), 2);
|
||||
}
|
||||
```
|
||||
|
||||
### 边界条件测试
|
||||
|
||||
确保覆盖边界情况：
|
||||
|
||||
```cpp
|
||||
// 空缓冲区
|
||||
TEST(BufferTest, ReadBuffer_EmptyBuffer_ReturnsZero)
|
||||
|
||||
// 零长度操作
|
||||
TEST(BufferTest, WriteBuffer_ZeroLength_ReturnsTrue)
|
||||
|
||||
// 请求超过可用数据
|
||||
TEST(BufferTest, ReadBuffer_RequestExceedsAvailable_ReturnsAvailableOnly)
|
||||
|
||||
// 大数据量
|
||||
TEST(BufferTest, WriteBuffer_LargeData_HandlesCorrectly)
|
||||
```
|
||||
|
||||
### 参数化测试
|
||||
|
||||
对于需要多组数据验证的场景：
|
||||
|
||||
```cpp
|
||||
class BufferReadTest : public ::testing::TestWithParam<std::tuple<size_t, size_t, size_t>> {};
|
||||
|
||||
TEST_P(BufferReadTest, ReadBuffer_VariousLengths) {
|
||||
auto [writeLen, readLen, expectedRead] = GetParam();
|
||||
|
||||
CBuffer buffer;
|
||||
std::vector<BYTE> data(writeLen, 0x42);
|
||||
buffer.WriteBuffer(data.data(), writeLen);
|
||||
|
||||
std::vector<BYTE> result(readLen);
|
||||
ULONG actual = buffer.ReadBuffer(result.data(), readLen);
|
||||
|
||||
EXPECT_EQ(actual, expectedRead);
|
||||
}
|
||||
|
||||
INSTANTIATE_TEST_SUITE_P(
|
||||
ReadLengths,
|
||||
BufferReadTest,
|
||||
::testing::Values(
|
||||
std::make_tuple(10, 5, 5), // 正常读取
|
||||
std::make_tuple(5, 10, 5), // 请求超过可用
|
||||
std::make_tuple(0, 5, 0), // 空缓冲区
|
||||
std::make_tuple(100, 0, 0) // 零长度读取
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
### 线程安全测试（服务端 Buffer）
|
||||
|
||||
```cpp
|
||||
TEST(ServerBufferTest, ConcurrentReadWrite_NoDataCorruption) {
|
||||
CBuffer buffer;
|
||||
std::atomic<bool> running{true};
|
||||
|
||||
// 写线程
|
||||
std::thread writer([&]() {
|
||||
BYTE data[100];
|
||||
while (running) {
|
||||
buffer.WriteBuffer(data, sizeof(data));
|
||||
}
|
||||
});
|
||||
|
||||
// 读线程
|
||||
std::thread reader([&]() {
|
||||
BYTE data[50];
|
||||
while (running) {
|
||||
buffer.ReadBuffer(data, sizeof(data));
|
||||
}
|
||||
});
|
||||
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(100));
|
||||
running = false;
|
||||
|
||||
writer.join();
|
||||
reader.join();
|
||||
|
||||
// 验证无崩溃即为成功
|
||||
SUCCEED();
|
||||
}
|
||||
```
|
||||
|
||||
## 运行测试
|
||||
|
||||
### 使用 test.bat (推荐)
|
||||
|
||||
Windows 下最简单的方式是使用 `test.bat` 脚本：
|
||||
|
||||
```batch
|
||||
cd test
|
||||
|
||||
test.bat build # 构建测试 (14 个可执行文件)
|
||||
test.bat run # 运行所有测试 (763 个)
|
||||
test.bat run client # 只运行客户端 Buffer 测试 (33)
|
||||
test.bat run server # 只运行服务端 Buffer 测试 (40)
|
||||
test.bat run protocol # 只运行协议测试 (58)
|
||||
test.bat run file # 只运行文件传输测试 (127)
|
||||
test.bat run network # 只运行网络通信测试 (80)
|
||||
test.bat run screen # 只运行图像处理测试 (425)
|
||||
test.bat run verbose # 详细模式运行
|
||||
test.bat clean # 清理构建目录
|
||||
test.bat rebuild # 清理后重新构建
|
||||
test.bat help # 显示帮助
|
||||
```
|
||||
|
||||
### CMake 手动构建
|
||||
|
||||
```bash
|
||||
cd test
|
||||
|
||||
# 配置
|
||||
cmake -B build -G "Visual Studio 17 2022"
|
||||
|
||||
# 构建
|
||||
cmake --build build --config Release
|
||||
|
||||
# 运行所有测试
|
||||
ctest --test-dir build -C Release --output-on-failure
|
||||
|
||||
# 运行特定测试
|
||||
ctest --test-dir build -C Release -R Client # 客户端测试
|
||||
ctest --test-dir build -C Release -R Server # 服务端测试
|
||||
|
||||
# 详细输出
|
||||
ctest --test-dir build -C Release -V
|
||||
```
|
||||
|
||||
### 直接运行可执行文件
|
||||
|
||||
```batch
|
||||
:: Phase 1: Buffer 测试
|
||||
test\build\Release\client_buffer_test.exe
|
||||
test\build\Release\server_buffer_test.exe
|
||||
|
||||
:: Phase 1: 协议测试
|
||||
test\build\Release\protocol_test.exe
|
||||
|
||||
:: Phase 2: 文件传输测试
|
||||
test\build\Release\file_transfer_test.exe
|
||||
test\build\Release\chunk_manager_test.exe
|
||||
test\build\Release\sha256_verify_test.exe
|
||||
test\build\Release\resume_state_test.exe
|
||||
|
||||
:: Phase 3: 网络通信测试
|
||||
test\build\Release\header_test.exe
|
||||
test\build\Release\packet_fragment_test.exe
|
||||
test\build\Release\http_mask_test.exe
|
||||
|
||||
:: Phase 4: 图像处理测试
|
||||
test\build\Release\diff_algorithm_test.exe
|
||||
test\build\Release\rgb565_test.exe
|
||||
test\build\Release\scroll_detector_test.exe
|
||||
test\build\Release\quality_adaptive_test.exe
|
||||
|
||||
:: 使用 gtest 过滤器
|
||||
header_test.exe --gtest_filter="*Encrypt*"
|
||||
rgb565_test.exe --gtest_filter="*Conversion*"
|
||||
|
||||
:: 列出所有测试（不运行）
|
||||
quality_adaptive_test.exe --gtest_list_tests
|
||||
|
||||
:: 输出 XML 报告
|
||||
protocol_test.exe --gtest_output=xml:report.xml
|
||||
```
|
||||
|
||||
## CI/CD 集成
|
||||
|
||||
### GitHub Actions 示例
|
||||
|
||||
```yaml
|
||||
name: Tests
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: windows-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Configure CMake
|
||||
working-directory: test
|
||||
run: cmake -B build -G "Visual Studio 17 2022"
|
||||
|
||||
- name: Build
|
||||
working-directory: test
|
||||
run: cmake --build build --config Release
|
||||
|
||||
- name: Run Tests
|
||||
working-directory: test
|
||||
run: ctest --test-dir build -C Release --output-on-failure
|
||||
|
||||
- name: Upload Test Results
|
||||
uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: test-results
|
||||
path: test/build/Release/*.xml
|
||||
```
|
||||
|
||||
## 覆盖率
|
||||
|
||||
### 使用 gcov/lcov (Linux)
|
||||
|
||||
```bash
|
||||
# 配置（启用覆盖率）
|
||||
cmake -B build -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug \
|
||||
-DCMAKE_CXX_FLAGS="--coverage"
|
||||
|
||||
# 构建并运行测试
|
||||
cmake --build build
|
||||
ctest --test-dir build
|
||||
|
||||
# 生成报告
|
||||
lcov --capture --directory build --output-file coverage.info
|
||||
genhtml coverage.info --output-directory coverage_report
|
||||
```
|
||||
|
||||
## 当前测试状态
|
||||
|
||||
**总计: 763 个测试用例，全部通过** ✅ (执行时间 < 3 秒)
|
||||
|
||||
### 已覆盖模块
|
||||
|
||||
| 阶段 | 模块 | 测试文件 | 用例数 | 状态 |
|
||||
|------|------|----------|--------|------|
|
||||
| Phase 1 | 客户端 Buffer | `unit/client/BufferTest.cpp` | 33 | ✅ |
|
||||
| Phase 1 | 服务端 Buffer | `unit/server/BufferTest.cpp` | 40 | ✅ |
|
||||
| Phase 1 | 协议/数据包 | `unit/protocol/PacketTest.cpp` | 39 | ✅ |
|
||||
| Phase 1 | 路径处理 | `unit/protocol/PathUtilsTest.cpp` | 19 | ✅ |
|
||||
| Phase 2 | V2 文件传输 | `unit/file/FileTransferV2Test.cpp` | 37 | ✅ |
|
||||
| Phase 2 | 分块管理 | `unit/file/ChunkManagerTest.cpp` | 36 | ✅ |
|
||||
| Phase 2 | SHA-256 校验 | `unit/file/SHA256VerifyTest.cpp` | 28 | ✅ |
|
||||
| Phase 2 | 断点续传 | `unit/file/ResumeStateTest.cpp` | 26 | ✅ |
|
||||
| Phase 3 | 协议头验证 | `unit/network/HeaderTest.cpp` | 29 | ✅ |
|
||||
| Phase 3 | 粘包/分包 | `unit/network/PacketFragmentTest.cpp` | 24 | ✅ |
|
||||
| Phase 3 | HTTP 伪装 | `unit/network/HttpMaskTest.cpp` | 27 | ✅ |
|
||||
| Phase 4 | 差分算法 | `unit/screen/DiffAlgorithmTest.cpp` | 32 | ✅ |
|
||||
| Phase 4 | RGB565 压缩 | `unit/screen/RGB565Test.cpp` | 286 | ✅ |
|
||||
| Phase 4 | 滚动检测 | `unit/screen/ScrollDetectorTest.cpp` | 43 | ✅ |
|
||||
| Phase 4 | 质量自适应 | `unit/screen/QualityAdaptiveTest.cpp` | 64 | ✅ |
|
||||
| | **合计** | | **763** | ✅ |
|
||||
|
||||
### 测试分布概览
|
||||
|
||||
| 阶段 | 测试类别 | 用例数 | 说明 |
|
||||
|------|---------|--------|------|
|
||||
| Phase 1 | Buffer 操作 | 73 | 读写、跳过、边界、线程安全 |
|
||||
| Phase 1 | 协议解析 | 58 | V2 数据包、路径处理 |
|
||||
| Phase 2 | 文件传输 | 127 | 分块、续传、校验 |
|
||||
| Phase 3 | 网络通信 | 80 | 包头、分包、伪装 |
|
||||
| Phase 4 | 图像处理 | 425 | 差分、RGB565、滚动、自适应 |
|
||||
|
||||
### 待测试模块
|
||||
|
||||
| 优先级 | 模块 | 说明 |
|
||||
|-------|------|------|
|
||||
| 中 | 系统管理 | 进程列表、服务管理 |
|
||||
| 中 | 终端 | 命令解析、输出处理 |
|
||||
| 低 | 压缩模块 | zstd 压缩/解压 |
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Google Test 官方文档](https://google.github.io/googletest/)
|
||||
- [Google Mock 入门](https://google.github.io/googletest/gmock_for_dummies.html)
|
||||
- [C++ 单元测试最佳实践](https://github.com/cpp-best-practices/cppbestpractices/blob/master/08-Considering_Safety.md)
|
||||
Reference in New Issue
Block a user