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
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 必须包含:

```cmake
add_test(NAME <TestName> COMMAND <executable>)
```

### 4.3 测试资源复制

如需复制测试资源:

```cmake
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

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

# 列出所有测试
ctest -N

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

---

## 6. CI 集成

### 6.1 GitHub Actions 配置

```yaml
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 本地验证

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

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

---

## 7. 测试实现规范

### 7.1 单元测试结构

```cpp
#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