XCEngine/docs/TESTING.md

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. 测试命名规范

// 格式: 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 浮点数比较

// 必须使用容差
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 常用断言

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)

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. 参数化测试

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 构建测试

# 创建构建目录
mkdir build && cd build

# 配置 CMake
cmake .. -G "Visual Studio 17 2022" -A x64

# 构建测试
cmake --build . --config Debug --target xcengine_math_tests

8.2 运行测试

# 运行所有测试
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 测试过滤器

# 运行所有 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. 持续集成

# .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 检测