feat: 添加Math库和Google Test测试框架
- 新增Math库: Vector2/3/4, Matrix3/4, Quaternion, Transform, Color等 - 新增测试框架: Google Test (gtest) - 新增140个单元测试，覆盖Vector, Matrix, Quaternion, Geometry - VolumeRenderer支持vcpkg的NanoVDB - 添加TESTING.md测试文档
This commit is contained in:
285
docs/TESTING.md
Normal file
285
docs/TESTING.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# XCEngine 测试体系文档
|
||||
|
||||
> **版本**: 1.0
|
||||
> **日期**: 2026-03-13
|
||||
|
||||
---
|
||||
|
||||
## 1. 测试架构
|
||||
|
||||
```
|
||||
tests/
|
||||
├── CMakeLists.txt # 测试构建配置
|
||||
├── run_tests.cmake # 测试运行脚本
|
||||
├── fixtures/ # 测试夹具
|
||||
│ └── MathFixtures.h
|
||||
├── math/ # Math 单元测试
|
||||
│ ├── CMakeLists.txt
|
||||
│ ├── test_vector.cpp
|
||||
│ ├── test_matrix.cpp
|
||||
│ ├── test_quaternion.cpp
|
||||
│ └── test_geometry.cpp
|
||||
├── core/ # Core 测试
|
||||
├── threading/ # 线程测试
|
||||
├── memory/ # 内存测试
|
||||
├── containers/ # 容器测试
|
||||
└── rendering/ # 渲染测试
|
||||
├── unit/ # 单元测试
|
||||
├── integration/ # 集成测试
|
||||
└── screenshots/ # 参考图
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 测试分类
|
||||
|
||||
| 类型 | 目录 | 目的 | 运行频率 |
|
||||
|------|------|------|---------|
|
||||
| **Unit Test** | `tests/*/` | 验证单个函数/类 | 每次提交 |
|
||||
| **Integration Test** | `tests/rendering/integration/` | 验证多模块协作 | 每次提交 |
|
||||
| **Benchmark** | `tests/benchmark/` | 性能回归检测 | 每日/每周 |
|
||||
| **Screenshot Test** | `tests/rendering/screenshots/` | 渲染正确性 | 每次提交 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试命名规范
|
||||
|
||||
```cpp
|
||||
// 格式: test_<模块>_<功能>_<场景>
|
||||
TEST(Math_Vector3, Dot_TwoVectors_ReturnsCorrectValue) { }
|
||||
TEST(Math_Vector3, Normalize_ZeroVector_ReturnsZeroVector) { }
|
||||
TEST(Math_Matrix4, Inverse_Identity_ReturnsIdentity) { }
|
||||
TEST(Math_Matrix4, TRS_Decompose_RecoversOriginalValues) { }
|
||||
TEST(Math_Quaternion, Slerp_ShortestPath_InterpolatesCorrectly) { }
|
||||
|
||||
// 边界情况
|
||||
TEST(Math_Vector3, Normalize_ZeroVector_DoesNotCrash) { }
|
||||
TEST(Math_Matrix4, Inverse_SingularMatrix_ReturnsIdentity) { }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 断言规范
|
||||
|
||||
### 4.1 浮点数比较
|
||||
|
||||
```cpp
|
||||
// 必须使用容差
|
||||
EXPECT_NEAR(actual, expected, 1e-5f);
|
||||
ASSERT_FLOAT_EQ(actual, expected); // gtest 内部有容差
|
||||
|
||||
// 数组比较
|
||||
for (int i = 0; i < 4; i++) {
|
||||
EXPECT_NEAR(actual.m[i], expected.m[i], 1e-5f);
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 常用断言
|
||||
|
||||
```cpp
|
||||
EXPECT_TRUE(condition);
|
||||
EXPECT_FALSE(condition);
|
||||
EXPECT_EQ(actual, expected);
|
||||
EXPECT_NE(actual, expected);
|
||||
EXPECT_STREQ(actual, expected);
|
||||
EXPECT_THROW(expression, exception_type);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试夹具 (Fixture)
|
||||
|
||||
```cpp
|
||||
class MathFixture : public ::testing::Test {
|
||||
protected:
|
||||
void SetUp() override {
|
||||
v1 = Vector3(1, 0, 0);
|
||||
v2 = Vector3(0, 1, 0);
|
||||
v3 = Vector3(1, 1, 1);
|
||||
|
||||
m1 = Matrix4x4::Identity();
|
||||
m2 = Matrix4x4::Translation(Vector3(1, 2, 3));
|
||||
}
|
||||
|
||||
Vector3 v1, v2, v3;
|
||||
Matrix4x4 m1, m2;
|
||||
const float epsilon = 1e-5f;
|
||||
};
|
||||
|
||||
TEST_F(MathFixture, Dot_OrthogonalVectors_ReturnsZero) {
|
||||
EXPECT_FLOAT_EQ(Vector3::Dot(v1, v2), 0.0f);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 参数化测试
|
||||
|
||||
```cpp
|
||||
class MatrixInverseTest : public ::testing::TestWithParam<Matrix4x4> {};
|
||||
|
||||
INSTANTIATE_TEST_SUITE_P(
|
||||
InverseCases,
|
||||
MatrixInverseTest,
|
||||
testing::Values(
|
||||
Matrix4x4::Identity(),
|
||||
Matrix4x4::Translation(Vector3(1,2,3)),
|
||||
Matrix4x4::Scale(Vector3(2,2,2))
|
||||
)
|
||||
);
|
||||
|
||||
TEST_P(MatrixInverseTest, InverseOfInverse_EqualsOriginal) {
|
||||
Matrix4x4 original = GetParam();
|
||||
Matrix4x4 inverted = original.Inverse();
|
||||
Matrix4x4 recovered = inverted.Inverse();
|
||||
|
||||
for (int i = 0; i < 4; i++) {
|
||||
for (int j = 0; j < 4; j++) {
|
||||
EXPECT_NEAR(original.m[i][j], recovered.m[i][j], 1e-4f);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Math 测试用例
|
||||
|
||||
### 7.1 Vector2/3/4 测试
|
||||
|
||||
| 测试类别 | 测试用例 |
|
||||
|---------|---------|
|
||||
| **构造** | 默认构造、参数构造、从 Vector3 构造 |
|
||||
| **运算** | 加、减、乘、除、点积、叉积 |
|
||||
| **归一化** | Normalize、Normalized、Magnitude、SqrMagnitude |
|
||||
| **插值** | Lerp、MoveTowards |
|
||||
| **投影** | Project、ProjectOnPlane |
|
||||
| **角度** | Angle、Reflect |
|
||||
|
||||
### 7.2 Matrix 测试
|
||||
|
||||
| 测试类别 | 测试用例 |
|
||||
|---------|---------|
|
||||
| **构造** | Identity、Zero |
|
||||
| **变换** | Translation、Rotation、Scale、TRS |
|
||||
| **相机** | LookAt、Perspective、Orthographic |
|
||||
| **运算** | 乘法、点乘、叉乘 |
|
||||
| **分解** | Inverse、Transpose、Determinant、Decompose |
|
||||
|
||||
### 7.3 Quaternion 测试
|
||||
|
||||
| 测试类别 | 测试用例 |
|
||||
|---------|---------|
|
||||
| **构造** | Identity、FromAxisAngle、FromEulerAngles |
|
||||
| **转换** | ToEulerAngles、ToMatrix4x4、FromRotationMatrix |
|
||||
| **插值** | Slerp |
|
||||
| **运算** | 乘法和逆 |
|
||||
|
||||
### 7.4 几何测试
|
||||
|
||||
| 测试类型 | 测试用例 |
|
||||
|---------|---------|
|
||||
| **Ray** | GetPoint、Intersects(Sphere/Box/Plane) |
|
||||
| **Sphere** | Contains、Intersects |
|
||||
| **Box** | Contains、Intersects |
|
||||
| **Plane** | FromPoints、GetDistanceToPoint、Intersects |
|
||||
| **Frustum** | Contains(Point/Sphere/Bounds)、Intersects |
|
||||
| **Bounds** | GetMinMax、Intersects、Contains、Encapsulate |
|
||||
|
||||
---
|
||||
|
||||
## 8. 构建与运行
|
||||
|
||||
### 8.1 构建测试
|
||||
|
||||
```bash
|
||||
# 创建构建目录
|
||||
mkdir build && cd build
|
||||
|
||||
# 配置 CMake
|
||||
cmake .. -G "Visual Studio 17 2022" -A x64
|
||||
|
||||
# 构建测试
|
||||
cmake --build . --config Debug --target xcengine_math_tests
|
||||
```
|
||||
|
||||
### 8.2 运行测试
|
||||
|
||||
```bash
|
||||
# 运行所有测试
|
||||
ctest --output-on-failure
|
||||
|
||||
# 运行 Math 测试
|
||||
./tests/xcengine_math_tests.exe
|
||||
|
||||
# 运行特定测试
|
||||
./tests/xcengine_math_tests.exe --gtest_filter=Math_Vector3.*
|
||||
|
||||
# 运行测试并显示详细信息
|
||||
./tests/xcengine_math_tests.exe --gtest_also_run_disabled_tests --gtest_print_time=1
|
||||
```
|
||||
|
||||
### 8.3 测试过滤器
|
||||
|
||||
```bash
|
||||
# 运行所有 Vector3 测试
|
||||
--gtest_filter=Math_Vector3.*
|
||||
|
||||
# 运行除某测试外的所有测试
|
||||
--gtest_filter=-Math_Matrix4.SingularMatrix*
|
||||
|
||||
# 运行多个测试
|
||||
--gtest_filter=Math_Vector3.*:Math_Matrix4.*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 覆盖率要求
|
||||
|
||||
| 模块 | 最低覆盖率 | 关键测试 |
|
||||
|------|-----------|---------|
|
||||
| Math | 90% | 所有公开 API |
|
||||
| Core | 80% | 智能指针、Event |
|
||||
| Containers | 85% | 边界、迭代器 |
|
||||
| Memory | 90% | 分配/泄漏 |
|
||||
| Threading | 70% | 基本功能 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 持续集成
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test.yml
|
||||
name: Test
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: windows-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Configure
|
||||
run: cmake -B build -DENABLE_COVERAGE=ON
|
||||
|
||||
- name: Build
|
||||
run: cmake --build build --config Debug
|
||||
|
||||
- name: Test
|
||||
run: ctest --test-dir build --output-on-failure
|
||||
|
||||
- name: Coverage
|
||||
run: cmake --build build --target coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 注意事项
|
||||
|
||||
1. **浮点数比较** - 必须使用容差 (通常 1e-5 或 1e-6)
|
||||
2. **边界条件** - 必须测试零向量、奇异矩阵等
|
||||
3. **随机性** - 如需固定 seed 保证确定性
|
||||
4. **线程安全** - 线程测试需设置超时
|
||||
5. **内存泄漏** - 使用 Valgrind 或 CRT 检测
|
||||
4564
docs/XCEngine渲染引擎架构设计.md
Normal file
4564
docs/XCEngine渲染引擎架构设计.md
Normal file
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
151
docs/plan/第一阶段计划.md
Normal file
151
docs/plan/第一阶段计划.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# XCEngine 渲染引擎 - 第一阶段计划
|
||||
|
||||
> **目标**: 构建核心基础层，为上层渲染系统提供底层依赖
|
||||
> **版本**: 1.0
|
||||
> **日期**: 2026-03-13
|
||||
|
||||
---
|
||||
|
||||
## 阶段目标
|
||||
|
||||
第一阶段聚焦于引擎底层基础设施的建设，确保后续渲染系统开发有稳定的基础。
|
||||
|
||||
---
|
||||
|
||||
## 模块规划
|
||||
|
||||
### 1.1 数学库 (Math Library)
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **预计工作量** | 5天 |
|
||||
| **包含类型** | `Vector2`, `Vector3`, `Vector4`, `Matrix3x3`, `Matrix4x4`, `Quaternion`, `Transform`, `Color`, `Rect`, `RectInt`, `Viewport`, `Ray`, `Sphere`, `Box`, `Plane`, `Frustum`, `Bounds`, `AABB`, `OBB` |
|
||||
| **功能要求** | 向量运算、矩阵变换、四元数、欧拉角转换、视锥体剔除基础 |
|
||||
|
||||
### 1.2 Core 基础类型
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **预计工作量** | 2天 |
|
||||
| **包含类型** | 基础类型别名 (`int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `byte`)、`RefCounted`、`Ref<T>`、`UniqueRef<T>`、`Event<T>` |
|
||||
| **功能要求** | 基础类型别名、引用计数、智能指针、事件系统 |
|
||||
| **依赖** | 无 |
|
||||
|
||||
### 1.3 线程系统 (Threading)
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **预计工作量** | 4天 |
|
||||
| **包含类型** | `ITask`, `LambdaTask`, `TaskGroup`, `TaskSystem`, `TaskSystemConfig`, `Mutex`, `SpinLock`, `ReadWriteLock`, `Thread` |
|
||||
| **功能要求** | 任务调度、依赖管理、并行计算、同步原语 |
|
||||
| **依赖** | Core基础类型 |
|
||||
|
||||
### 1.4 内存管理 (Memory Management)
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **预计工作量** | 3天 |
|
||||
| **包含类型** | `IAllocator`, `LinearAllocator`, `PoolAllocator`, `ProxyAllocator`, `MemoryManager` |
|
||||
| **功能要求** | 内存分配、追踪、泄漏检测、线性/池化分配策略 |
|
||||
| **依赖** | 线程系统（ProxyAllocator需要Mutex） |
|
||||
|
||||
### 1.5 容器库 (Containers)
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **预计工作量** | 3天 |
|
||||
| **包含类型** | `Array<T>`, `String`, `String::npos`, `HashMap<K,V>` |
|
||||
| **功能要求** | 动态数组、字符串操作（含npos常量）、哈希映射 |
|
||||
| **依赖** | Core基础类型, 内存管理 |
|
||||
|
||||
### 1.6 日志与调试系统
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **优先级** | P1 |
|
||||
| **预计工作量** | 2天 |
|
||||
| **包含类型** | `Logger`, `ConsoleLogSink`, `FileLogSink`, `FileWriter`, `Profiler`, `Assert` |
|
||||
| **功能要求** | 分级日志、分类输出、文件写入、性能分析、断言 |
|
||||
| **依赖** | Core基础类型, 容器库(String) |
|
||||
|
||||
---
|
||||
|
||||
## 时间安排
|
||||
|
||||
| 周次 | 内容 |
|
||||
|------|------|
|
||||
| 第1周 | 数学库 + Core基础类型 |
|
||||
| 第2周 | 线程系统 + 内存管理 |
|
||||
| 第3周 | 容器库 + 日志系统 |
|
||||
|
||||
> 注：内存管理依赖线程系统完成（ProxyAllocator需要Mutex），因此调整顺序
|
||||
|
||||
---
|
||||
|
||||
## 测试方案
|
||||
|
||||
### 测试框架
|
||||
- **推荐**: Google Test (gtest) 或 Doctest
|
||||
|
||||
### 测试用例设计
|
||||
|
||||
| 模块 | 测试类别 | 测试用例示例 |
|
||||
|------|---------|-------------|
|
||||
| **Math** | 向量运算 | `Vector3::Dot`, `Cross`, `Normalize`, `Lerp` 精度测试 |
|
||||
| **Math** | 矩阵运算 | `Matrix4x4::TRS`, `LookAt`, `Perspective` 结果正确性 |
|
||||
| **Math** | 四元数 | `FromEulerAngles`, `Slerp`, `ToMatrix4x4` 精度验证 |
|
||||
| **Core** | 引用计数 | `RefCounted` 多线程安全释放 |
|
||||
| **Core** | 事件系统 | 订阅/取消订阅、线程安全调用 |
|
||||
| **Threading** | 任务系统 | 依赖链、优先级、并行For、TaskSystemConfig |
|
||||
| **Threading** | 同步原语 | 锁竞争、死锁检测 |
|
||||
| **Memory** | 分配器 | 边界检查、碎片率、线性分配器回滚测试 |
|
||||
| **Memory** | 泄漏检测 | 分配/释放计数、峰值追踪 |
|
||||
| **Containers** | Array | 边界访问、迭代器、内存增长策略 |
|
||||
| **Containers** | String | 子串、查找、大小写转换 |
|
||||
| **Containers** | HashMap | 冲突处理、负载因子重分布 |
|
||||
| **Logger** | 日志级别 | 过滤、分类、格式化 |
|
||||
|
||||
### 执行命令
|
||||
|
||||
```bash
|
||||
# 编译并运行所有单元测试
|
||||
cmake --build build --target xcengine_tests
|
||||
./build/tests/xcengine_tests.exe
|
||||
|
||||
# 性能基准测试
|
||||
./build/tests/xcengine_tests.exe --benchmark
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 数学库通过全部运算正确性测试
|
||||
- [ ] Core基础类型（引用计数、智能指针）工作正常
|
||||
- [ ] 线程系统在高并发下稳定运行
|
||||
- [ ] 内存分配器无内存泄漏
|
||||
- [ ] 容器操作边界安全
|
||||
- [ ] 日志系统输出格式正确
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```
|
||||
Math Library (无依赖)
|
||||
│
|
||||
├──▶ Core 基础类型 (无依赖)
|
||||
│ │
|
||||
│ ├──▶ Threading (依赖 Core)
|
||||
│ │
|
||||
│ ├──▶ Memory Management (依赖 Threading)
|
||||
│ │ │
|
||||
│ │ └──▶ Containers (依赖 Memory, Core)
|
||||
│ │
|
||||
│ └──▶ Logging & Debug (依赖 Core, Containers)
|
||||
```
|
||||
Reference in New Issue
Block a user