xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: improve test infrastructure and fix OpenGL GLAD initialization

Browse Source 
- Rename D3D12Enum.h to D3D12Enums.h for naming consistency
- Fix OpenGL unit test GLAD initialization by using gladLoadGL()
  instead of gladLoadGLLoader(wglGetProcAddress) for fallback support
- Migrate remaining tests to use gtest_discover_tests for granular
  test discovery (math, core, containers, memory, threading, debug,
  components, scene, resources, input, opengl)
- Remove obsolete TEST_RESOURCES_DIR and copy_directory commands
  from OpenGL unit test CMakeLists (minimal/Res doesn't exist)
- Update TEST_SPEC.md with performance metrics and per-module
  build/test commands for faster development workflow
- Update CMake path references to use lowercase paths
This commit is contained in:
ssdfasd
2026-03-23 00:43:02 +08:00
parent 0f0ab8922a
commit f427699ac6
100 changed files with 1191 additions and 1136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
tests/TEST_SPEC.md
View File

@@ -2,239 +2,208 @@
## 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 |
| 组件 | 用途 |
|------|------|
| Google Test | 单元测试框架 |
| CTest | CMake 测试发现和执行 |
---
## 2. 测试目录结构
### 2.1 整体结构
```
tests/
├── CMakeLists.txt # 主 CMake 配置
├── TEST_SPEC.md # 本规范文档
├── run_tests.bat # Windows 测试启动脚本
├── CMakeLists.txt # 主 CMake 配置 (包含 enable_testing)
├── fixtures/ # 共享测试夹具
├── scripts/
│ └── run_tests.py # 统一测试运行脚本
├── math/ # 数学库测试
├── core/ # 核心库测试
├── containers/ # 容器测试
├── containers/ # 容器测试
├── memory/ # 内存管理测试
├── threading/ # 线程测试
├── debug/ # 调试系统测试
├── Resources/ # 资源系统测试
└── RHI/
├── D3D12/ # D3D12 RHI 测试
│ ├── unit/ # 单元测试
│ └── integration/ # 集成测试
└── OpenGL/ # OpenGL RHI 测试 (暂不维护)
├── resources/ # 资源系统测试
├── input/ # 输入模块测试
├── scene/ # 场景测试
├── components/ # 组件测试
└── rhi/
├── d3d12/ # D3D12 RHI 测试
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── CMakeLists.txt
└── opengl/ # OpenGL RHI 测试
├── unit/ # 单元测试
├── integration/ # 集成测试
└── CMakeLists.txt
```
### 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. 模块命名
### 3.1 单元测试命名
| 模块 | 可执行文件 | CTest 名称前缀 |
|------|----------|---------------|
| math | math_tests | Math_* |
| core | core_tests | Core_* |
| containers | containers_tests | Containers_* |
| memory | memory_tests | MemoryTest_* |
| threading | threading_tests | Threading_* |
| debug | debug_tests | Debug_* |
| resources | resources_tests | Resource*/Texture*/Mesh* 等 |
| input | input_tests | Input*/WindowsInput* |
| scene | scene_tests | Scene*/SceneManager_* |
| components | components_tests | Component_*|TransformComponent_* |
| RHI/D3D12 | rhi_d3d12_tests | D3D12*Fixture/SwapChain*Fixture |
| RHI/OpenGL | opengl_engine_tests | OpenGLTestFixture.* |
---
## 4. 测试用例命名
**格式**: `Component_Category_SubBehavior`
| 部分 | 说明 | 示例 |
|------|------|------|
| Component | 被测组件 | Memory, ResourceHandle, Buffer |
| Component | 被测组件 | Memory, Buffer, Texture |
| Category | 操作类别 | Create, Get, Set, Map, Reset |
| SubBehavior | 具体行为 | DefaultHeap, GPUAddress, ValidPointer |
**示例**:
```
MemoryTest_GetSystemAllocator_ReturnsValidPointer
ResourceHandle_DefaultConstructor
Buffer_Create_DefaultHeap
Texture_Create_2D
Fence_Signal_Wait
```
### 3.2 禁止模式
❌ 不允许:
**禁止模式**:
- `*_Placeholder` - 无意义的占位测试
- 驼峰+下划线混用
- 空操作测试
### 3.3 大小写规则
- 全小写，单词间用下划线分隔
- Component 名称与类名一致
---
## 4. CMakeLists.txt 规范
## 5. CMake 规范
### 4.1 单元测试模板
### 5.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})
add_executable(module_tests ${TEST_SOURCES})
# MSVC 运行时库排除
if(MSVC)
set_target_properties(xcengine_module_tests PROPERTIES
set_target_properties(module_tests PROPERTIES
LINK_FLAGS "/NODEFAULTLIB:libcpmt.lib /NODEFAULTLIB:libcmt.lib"
)
endif()
target_link_libraries(xcengine_module_tests PRIVATE
target_link_libraries(module_tests PRIVATE
XCEngine
GTest::gtest
GTest::gtest_main
)
target_include_directories(xcengine_module_tests PRIVATE
target_include_directories(module_tests PRIVATE
${CMAKE_SOURCE_DIR}/engine/include
${CMAKE_SOURCE_DIR}/tests/fixtures
)
add_test(NAME ModuleTests COMMAND xcengine_module_tests)
include(GoogleTest)
gtest_discover_tests(module_tests)
```
### 4.2 CTest 注册
每个模块的 CMakeLists.txt 必须包含:
### 5.2 RHI 测试 CMakeLists 模板
```cmake
add_test(NAME <TestName> COMMAND <executable>)
```
cmake_minimum_required(VERSION 3.15)
### 4.3 测试资源复制
project(rhi_backend_tests)
如需复制测试资源:
find_package(GTest REQUIRED)
find_package(Python3 REQUIRED) # 集成测试需要
```cmake
add_custom_command(TARGET <test> POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_directory
${CMAKE_CURRENT_SOURCE_DIR}/Res
$<TARGET_FILE_DIR:<test>>/Res
# 单元测试
set(UNIT_TEST_SOURCES
fixtures/TestFixture.cpp
test_*.cpp
)
add_executable(rhi_backend_tests ${UNIT_TEST_SOURCES})
target_link_libraries(rhi_backend_tests PRIVATE
d3d12
dxgi
d3dcompiler
XCEngine
GTest::gtest
GTest::gtest_main
)
target_include_directories(rhi_backend_tests PRIVATE
${CMAKE_CURRENT_SOURCE_DIR}/fixtures
${CMAKE_SOURCE_DIR}/engine/include
${CMAKE_SOURCE_DIR}/engine/src
)
# 集成测试
add_subdirectory(integration)
include(GoogleTest)
gtest_discover_tests(rhi_backend_tests)
```
---
## 5. 测试执行
## 6. 测试执行
### 5.1 统一测试脚本
### 6.1 增量构建（推荐）
**位置**: `scripts/run_tests.py`
**何时需要重新运行 `cmake ..`**：
- 新增/删除/重命名源文件
- 修改 CMakeLists.txt（添加 subdirectory、target 等）
- 修改编译器选项或宏定义
**功能**:
- 跨平台支持 (Windows/Linux)
- 自动检测测试目录
- 单元测试 + 集成测试
- 测试结果汇总
**增量构建命令**：
```bash
# 1. 增量配置（检测 CMakeLists.txt 变化）
cd build
cmake ..
### 5.2 使用方式
# 2. 只构建特定 target（不重新配置整个项目）
cmake --build . --target math_tests --config Debug
| 命令 | 说明 |
|------|------|
| `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` | 详细输出 |
# 3. 只构建特定模块
cmake --build . --target rhi_d3d12_tests --config Debug
```
### 5.3 直接使用 CTest
### 6.2 完整构建
```bash
# 运行特定模块测试
cd build/tests/<module>
ctest -C Debug --output-on-failure
cmake --build build --config Debug
cd build && ctest -C Debug --output-on-failure
```
### 6.3 测试运行
```bash
# 列出所有测试
ctest -N
# 运行所有测试
ctest -C Debug --output-on-failure
```
---
# 运行特定模块测试
ctest -R "Math_" -C Debug --output-on-failure
## 6. CI 集成
# 运行 D3D12 所有测试
ctest -R "D3D12" -C Debug --output-on-failure
### 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
# 运行特定测试用例
ctest -R "Buffer_Create" -C Debug --output-on-failure
```
---
@@ -247,37 +216,19 @@ python scripts/run_tests.py --unit-only
#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 {
// 清理资源
}
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 断言选择
### 7.2 断言选择
| 断言 | 用途 |
|------|------|
@@ -286,43 +237,117 @@ TEST_F(ComponentTest, GetProperty_ReturnsExpectedValue) {
---
## 8. 文件结构
## 8. CI 配置
```
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/
```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: cd build && ctest -C Debug --output-on-failure
```
---
## 9. 规范更新记录
## 9. 性能参考
| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0 | 2026-03-20 | 初始版本，统一测试规范体系 |
### 9.1 模块构建和运行时间
| 模块 | 构建时间 | 运行时间 | 测试数量 |
|------|---------|---------|----------|
| math | ~6s | ~26s | 140 |
| core | ~6s | ~4s | 18 |
| containers | ~3s | ~10s | 51 |
| memory | ~3s | ~4s | 19 |
| threading | ~5s | ~4s | 13 |
| debug | ~3s | ~2s | 8 |
| components | ~3s | ~8s | 39 |
| scene | ~4s | ~2s | 14 |
| resources | ~4s | ~31s | 131 |
| input | ~4s | ~9s | 40 |
| D3D12 unit | ~3s | ~55s | 49 |
| OpenGL unit | ~46s | ~11s | 61 |
| **总计** | - | - | **~622** |
### 9.2 分模块构建命令（推荐）
```bash
# ==================== 快速开发工作流 ====================
# 1. 修改某个模块代码后，增量构建该模块
cmake --build . --target math_tests --config Debug
cmake --build . --target core_tests --config Debug
cmake --build . --target containers_tests --config Debug
cmake --build . --target memory_tests --config Debug
cmake --build . --target threading_tests --config Debug
cmake --build . --target debug_tests --config Debug
cmake --build . --target components_tests --config Debug
cmake --build . --target scene_tests --config Debug
cmake --build . --target resources_tests --config Debug
cmake --build . --target input_tests --config Debug
cmake --build . --target rhi_d3d12_tests --config Debug
cmake --build . --target opengl_engine_tests --config Debug
# 2. 只运行该模块测试
ctest -R "^Math_" -C Debug --output-on-failure
ctest -R "^Core_" -C Debug --output-on-failure
ctest -R "^Containers_" -C Debug --output-on-failure
ctest -R "MemoryTest_|LinearAllocator|PoolAllocator" -C Debug --output-on-failure
ctest -R "^Threading_" -C Debug --output-on-failure
ctest -R "^Debug_" -C Debug --output-on-failure
ctest -R "Component_Test|TransformComponent_" -C Debug --output-on-failure
ctest -R "^Scene_" -C Debug --output-on-failure
ctest -R "Resource[A-Z]|Texture[A-Z]|Mesh[A-Z]|Shader[A-Z]|Audio[A-Z]|Material[A-Z]" -C Debug --output-on-failure
ctest -R "Input|WindowsInput" -C Debug --output-on-failure
ctest -R "D3D12.*Fixture|SwapChain.*Fixture" -C Debug --output-on-failure
build/tests/RHI/OpenGL/unit/Debug/opengl_engine_tests.exe --gtest_filter=*
```
### 9.3 按功能组构建和运行
```bash
# ==================== 基础设施模块 ====================
cmake --build . --target math_tests --config Debug
cmake --build . --target core_tests --config Debug
cmake --build . --target containers_tests --config Debug
ctest -R "^Math_|^Core_|^Containers_" -C Debug --output-on-failure
# ==================== 核心系统模块 ====================
cmake --build . --target memory_tests --config Debug
cmake --build . --target threading_tests --config Debug
cmake --build . --target debug_tests --config Debug
ctest -R "MemoryTest_|LinearAllocator|PoolAllocator|^Threading_|^Debug_" -C Debug --output-on-failure
# ==================== 游戏引擎模块 ====================
cmake --build . --target components_tests --config Debug
cmake --build . --target scene_tests --config Debug
cmake --build . --target resources_tests --config Debug
cmake --build . --target input_tests --config Debug
ctest -R "Component_Test|TransformComponent_|^Scene_|Resource[A-Z]|Texture[A-Z]|Mesh[A-Z]|Input|WindowsInput" -C Debug --output-on-failure
# ==================== RHI 模块 ====================
cmake --build . --target rhi_d3d12_tests --config Debug
cmake --build . --target opengl_engine_tests --config Debug
ctest -R "D3D12.*Fixture|SwapChain.*Fixture" -C Debug --output-on-failure
build/tests/RHI/OpenGL/unit/Debug/opengl_engine_tests.exe --gtest_filter=*
```
### 9.4 注意事项
- **OpenGL 单元测试**：构建时间较长(~46s)，因为需要编译 glad.c。建议单独构建
- **D3D12 单元测试**：运行时间较长(~55s)，适合 CI 自动化
- **Resources 模块**：运行时间~31s，包含大量资源加载测试
- **Math 模块**：运行时间~26s，包含140个数学运算测试
---
**规范版本**: 1.0
**最后更新**: 2026-03-20
**最后更新**: 2026-03-23