XCEngine/tests/TEST_SPEC.md

XCEngine 测试规范

1. 测试框架

1.1 框架组成

组件	用途	文档位置
Google Test	单元测试框架	https://google.github.io/googletest/
CTest	CMake 测试发现和执行	内置 CMake 模块
Python	集成测试辅助	scripts/run_tests.py

1.2 测试分类

类型	框架	特点
单元测试	Google Test	快速、独立、无副作用
集成测试	CTest + Python	端到端验证、需要 GUI

---

2. 测试目录结构

2.1 整体结构

tests/
├── CMakeLists.txt              # 主 CMake 配置
├── TEST_SPEC.md                # 本规范文档
├── run_tests.bat              # Windows 测试启动脚本
├── fixtures/                   # 共享测试夹具
├── scripts/
│   └── run_tests.py           # 统一测试运行脚本
├── math/                      # 数学库测试
├── core/                      # 核心库测试
├── containers/                 # 容器测试
├── memory/                    # 内存管理测试
├── threading/                 # 线程测试
├── debug/                    # 调试系统测试
├── Resources/                 # 资源系统测试
└── RHI/
    ├── D3D12/               # D3D12 RHI 测试
    │   ├── unit/            # 单元测试
    │   └── integration/     # 集成测试
    └── OpenGL/              # OpenGL RHI 测试 (暂不维护)

2.2 模块命名规范

模块	测试可执行文件	CTest 名称
math	xcengine_math_tests	MathTests
core	xcengine_core_tests	CoreTests
containers	xcengine_containers_tests	ContainersTests
memory	xcengine_memory_tests	MemoryTests
threading	xcengine_threading_tests	ThreadingTests
debug	xcengine_debug_tests	DebugTests
Resources	xcengine_resources_tests	ResourcesTests
RHI/D3D12/unit	d3d12_engine_tests	D3D12EngineTests
RHI/D3D12/integration	D3D12_Minimal	D3D12_Minimal_Integration

---

3. 测试命名规范

3.1 单元测试命名

格式: Component_Category_SubBehavior

部分	说明	示例
Component	被测组件	Memory, ResourceHandle, Buffer
Category	操作类别	Create, Get, Set, Map, Reset
SubBehavior	具体行为	DefaultHeap, GPUAddress, ValidPointer

示例:

MemoryTest_GetSystemAllocator_ReturnsValidPointer
ResourceHandle_DefaultConstructor
Buffer_Create_DefaultHeap
Texture_Create_2D

3.2 禁止模式

❌ 不允许:

• *_Placeholder - 无意义的占位测试
• 驼峰+下划线混用
• 空操作测试

3.3 大小写规则

• 全小写，单词间用下划线分隔
• Component 名称与类名一致

---

4. CMakeLists.txt 规范

4.1 单元测试模板

cmake_minimum_required(VERSION 3.15)

project(XCEngine_ModuleTests)

find_package(GTest REQUIRED)

set(TEST_SOURCES
    test_module.cpp
    # ... 其他测试文件
)

add_executable(xcengine_module_tests ${TEST_SOURCES})

# MSVC 运行时库排除
if(MSVC)
    set_target_properties(xcengine_module_tests PROPERTIES
        LINK_FLAGS "/NODEFAULTLIB:libcpmt.lib /NODEFAULTLIB:libcmt.lib"
    )
endif()

target_link_libraries(xcengine_module_tests PRIVATE
    XCEngine
    GTest::gtest
    GTest::gtest_main
)

target_include_directories(xcengine_module_tests PRIVATE
    ${CMAKE_SOURCE_DIR}/engine/include
    ${CMAKE_SOURCE_DIR}/tests/fixtures
)

add_test(NAME ModuleTests COMMAND xcengine_module_tests)

4.2 CTest 注册

每个模块的 CMakeLists.txt 必须包含:

add_test(NAME <TestName> COMMAND <executable>)

4.3 测试资源复制

如需复制测试资源:

add_custom_command(TARGET <test> POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        ${CMAKE_CURRENT_SOURCE_DIR}/Res
        $<TARGET_FILE_DIR:<test>>/Res
)

---

5. 测试执行

5.1 统一测试脚本

位置: scripts/run_tests.py

功能:

• 跨平台支持 (Windows/Linux)
• 自动检测测试目录
• 单元测试 + 集成测试
• 测试结果汇总

5.2 使用方式

命令	说明
python scripts/run_tests.py	运行所有测试
python scripts/run_tests.py --unit-only	仅单元测试
python scripts/run_tests.py --integration	含集成测试
python scripts/run_tests.py --ci	CI 模式 (跳过 GUI 测试)
python scripts/run_tests.py --build	构建并测试
python scripts/run_tests.py --dir <path>	指定测试目录
python scripts/run_tests.py --verbose	详细输出

5.3 直接使用 CTest

# 运行特定模块测试
cd build/tests/<module>
ctest -C Debug --output-on-failure

# 列出所有测试
ctest -N

# 运行所有测试
ctest -C Debug --output-on-failure

---

6. CI 集成

6.1 GitHub Actions 配置

name: XCEngine Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Configure CMake
        run: cmake -B build -DCMAKE_BUILD_TYPE=Debug
      
      - name: Build
        run: cmake --build build --config Debug
      
      - name: Run Tests
        run: python scripts/run_tests.py --ci

6.2 CI 模式说明

--ci 模式会:

• 运行所有单元测试
• 跳过需要 GUI 窗口的集成测试
• 输出机器可读的测试结果

6.3 本地验证

# 完整构建和测试
python scripts/run_tests.py --build

# 仅验证单元测试
python scripts/run_tests.py --unit-only

---

7. 测试实现规范

7.1 单元测试结构

#include <gtest/gtest.h>
#include <XCEngine/Module/Component.h>

using namespace XCEngine::Module;

class ComponentTest : public ::testing::Test {
protected:
    void SetUp() override {
        // 初始化测试环境
    }
    
    void TearDown() override {
        // 清理资源
    }
};

TEST_F(ComponentTest, Create_ReturnsValidPointer) {
    auto component = Component::Create();
    ASSERT_NE(component, nullptr);
}

TEST_F(ComponentTest, GetProperty_ReturnsExpectedValue) {
    Component component;
    EXPECT_EQ(component.GetProperty(), expected_value);
}

7.2 Fixture 使用原则

• 每个测试类使用独立的 Fixture
• SetUp/TearDown 用于资源初始化/清理
• 避免测试间共享状态

7.3 断言选择

断言	用途
ASSERT_*	致命错误，立即终止测试
EXPECT_*	非致命错误，继续执行

---

8. 文件结构

tests/
├── CMakeLists.txt
├── TEST_SPEC.md                    # 本规范
├── run_tests.bat                   # Windows 测试脚本
├── fixtures/                      # 共享夹具头文件
├── scripts/
│   └── run_tests.py              # 统一测试运行脚本
├── math/
│   ├── CMakeLists.txt
│   └── test_*.cpp
├── core/
├── containers/
├── memory/
├── threading/
├── debug/
├── Resources/
└── RHI/
    ├── D3D12/
    │   ├── unit/
    │   ├── integration/
    │   ├── TEST_SPEC.md          # D3D12 专项规范
    │   └── TEST_IMPROVEMENT_PLAN.md
    └── OpenGL/

---

9. 规范更新记录

版本	日期	变更
1.0	2026-03-20	初始版本，统一测试规范体系

---

规范版本: 1.0
最后更新: 2026-03-20