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

Refresh test spec and align minimal shared GT

Browse Source
This commit is contained in:
ssdfasd
2026-03-25 23:41:45 +08:00
parent 8f9a2d17a5
commit 83cd2fa591
2 changed files with 178 additions and 560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
tests/RHI/integration/minimal/CMakeLists.txt
View File

@@ -45,7 +45,7 @@ add_custom_command(TARGET rhi_integration_minimal POST_BUILD
${CMAKE_SOURCE_DIR}/tests/RHI/integration/compare_ppm.py
$<TARGET_FILE_DIR:rhi_integration_minimal>/
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${CMAKE_SOURCE_DIR}/tests/RHI/D3D12/integration/minimal/GT.ppm
${CMAKE_CURRENT_SOURCE_DIR}/GT.ppm
$<TARGET_FILE_DIR:rhi_integration_minimal>/GT.ppm
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${ENGINE_ROOT_DIR}/third_party/renderdoc/renderdoc.dll

736
tests/TEST_SPEC.md
View File

@@ -1,602 +1,220 @@
# XCEngine 测试规范
## 1. 测试框架
最后更新：2026-03-25
| 组件 | 用途 |
| ----------- | -------------------- |
| Google Test | 单元测试框架 |
| CTest | CMake 测试发现和执行 |
## 1. 目标
---
本文件只描述当前工作区内已经存在并仍然有效的测试约定，重点覆盖：
## 2. 测试目录结构
- `tests/` 的整体组织方式
- CMake / CTest 的基本用法
- RHI 模块的测试分层
- RHI 抽象层集成测试的当前规范
```
如果代码、目录结构或 target 名称发生变化，应优先更新本文件，而不是继续累积过时说明。
## 2. 顶层结构
`tests/CMakeLists.txt` 当前纳入的测试子目录如下：
```text
tests/
├── CMakeLists.txt # 主 CMake 配置 (包含 enable_testing)
├── fixtures/ # 共享测试夹具
├── math/ # 数学库测试
├── Core/ # 核心库测试
│ ├── CMakeLists.txt
│ ├── Asset/ # Core/Asset 模块测试
│ │ ├── CMakeLists.txt
│ │ ├── test_iresource.cpp
│ │ ├── test_resource_types.cpp
│ │ ├── test_resource_guid.cpp
│ │ ├── test_resource_handle.cpp
│ │ ├── test_resource_cache.cpp
│ │ └── test_resource_dependency.cpp
│ └── IO/ # Core/IO 模块测试
│ ├── CMakeLists.txt
│ ├── test_iresource_loader.cpp
│ ├── test_resource_path.cpp
│ ├── test_resource_filesystem.cpp
│ ├── test_file_archive.cpp
│ └── test_resource_package.cpp
├── containers/ # 容器测试
├── memory/ # 内存管理测试
├── threading/ # 线程测试
├── debug/ # 调试系统测试
├── Resources/ # 资源系统测试 (按类型分目录)
│ ├── CMakeLists.txt
│ ├── Texture/ # 纹理资源测试
│ │ ├── CMakeLists.txt
│ │ ├── test_texture.cpp
│ │ ├── test_texture_loader.cpp
│ │ └── test_texture_import_settings.cpp
│ ├── Mesh/ # 网格资源测试
│ │ ├── CMakeLists.txt
│ │ ├── test_mesh.cpp
│ │ ├── test_mesh_loader.cpp
│ │ └── test_mesh_import_settings.cpp
│ ├── Material/ # 材质资源测试
│ │ ├── CMakeLists.txt
│ │ ├── test_material.cpp
│ │ └── test_material_loader.cpp
│ ├── Shader/ # 着色器资源测试
│ │ ├── CMakeLists.txt
│ │ ├── test_shader.cpp
│ │ └── test_shader_loader.cpp
│ └── AudioClip/ # 音频资源测试
│ ├── CMakeLists.txt
│ ├── test_audio_clip.cpp
│ └── test_audio_loader.cpp
├── input/ # 输入模块测试
├── scene/ # 场景测试
├── components/ # 组件测试
└── rhi/
├── CMakeLists.txt # RHI 测试主 CMake (包含 D3D12/OpenGL/unit/integration)
├── unit/ # RHI 抽象层单元测试 (参数化, 同时测 D3D12/OpenGL)
│ ├── CMakeLists.txt
│ ├── fixtures/
│ └── test_*.cpp
├── integration/ # RHI 抽象层集成测试 (共享夹具，参数化测 D3D12/OpenGL)
│ ├── CMakeLists.txt
│ ├── fixtures/
│ │ ├── RHIIntegrationFixture.h
│ │ └── RHIIntegrationFixture.cpp
│ └── minimal/ # 最小渲染测试
├── d3d12/ # D3D12 后端封装测试
│ ├── CMakeLists.txt
│ ├── unit/ # D3D12 单元测试
│ │ ├── fixtures/
│ │ └── test_*.cpp
│ └── integration/ # D3D12 集成测试 (minimal/triangle/quad/sphere)
└── opengl/ # OpenGL 后端封装测试
├── CMakeLists.txt
├── unit/ # OpenGL 单元测试
│ ├── fixtures/
│ └── test_*.cpp
└── integration/ # OpenGL 集成测试 (minimal/triangle/quad/sphere)
├─ math/
├─ core/
├─ containers/
├─ memory/
├─ threading/
├─ debug/
├─ components/
├─ scene/
├─ rhi/
├─ resources/
└─ input/
```
**注意**：Windows 文件系统大小写不敏感，`tests/Core/` 和 `tests/core/` 为同一目录。实际文件位于 `tests/core/`（小写），但 CMakeLists.txt 中配置为 `tests/Core/`（大写）。
说明：
### 2.1 RHI 测试分层架构
- 实际磁盘上的大小写有历史遗留差异；在 Windows 下通常不影响构建。
- 新增测试模块时，必须同时补充对应目录下的 `CMakeLists.txt`，并在 `tests/CMakeLists.txt` 中注册。
RHI 测试分为五个层次，各层测试目标不同：
## 3. 基本构建方式
| 层次 | 位置 | 测试目标 | 测试方式 |
| ------------------ | -------------------------- | --------------------------------- | ------------------------------------------------------------------- |
| **RHI抽象层单元** | `tests/RHI/unit/` | RHI接口定义、跨平台抽象、后端选择 | 参数化测试 (TEST_P)，一份代码同时测试 D3D12/OpenGL |
| **RHI抽象层集成** | `tests/RHI/integration/` | RHI接口渲染管线完整性验证 | 参数化测试 (TEST_P)，共享夹具同时测 D3D12/OpenGL，Python脚本对比PPM |
| **D3D12后端单元** | `tests/RHI/D3D12/unit/` | D3D12 API封装实现 | 非参数化测试 (TEST_F)，直接测试D3D12封装 |
| **OpenGL后端单元** | `tests/RHI/OpenGL/unit/` | OpenGL API封装实现 | 非参数化测试 (TEST_F)，直接测试OpenGL封装 |
| **后端集成测试** | `tests/RHI/*/integration/` | 多组件协作、渲染管线完整性 | Python脚本对比渲染输出PPM文件 |
推荐始终使用 CMake 驱动构建和测试，不再维护额外的手工脚本流程。
**注意**：五层测试不是冗余，而是测试不同层次的封装。各层测试可以验证：
- RHI抽象层单元测试验证接口兼容性和跨平台一致性
- RHI抽象层集成测试验证RHI接口的渲染管线完整性
- 后端专用测试验证各后端实现的正确性
- 后端集成测试验证完整渲染管线和多组件协作
### 3.1 配置
---
## 3. 模块命名
| 模块 | 可执行文件 | 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/Texture | resources_texture_tests | Texture_* |
| Resources/Mesh | resources_mesh_tests | Mesh_* |
| Resources/Material | resources_material_tests | Material_* |
| Resources/Shader | resources_shader_tests | Shader_* |
| Resources/AudioClip | resources_audioclip_tests | AudioClip_* |
| input | input_tests | Input*/WindowsInput* |
| scene | scene_tests | Scene*/SceneManager_* |
| components | components_tests | Component_* | TransformComponent_* |
| RHI/unit (抽象层单元) | rhi_unit_tests | D3D12/RHITestFixture.*<br>OpenGL/RHITestFixture.* |
| RHI/integration (抽象层集成) | rhi_integration_minimal | D3D12/MinimalTest.*<br>OpenGL/MinimalTest.* |
| RHI/D3D12/unit (后端) | rhi_d3d12_tests | D3D12TestFixture.*<br>SwapChainTestFixture.* |
| RHI/OpenGL/unit (后端) | rhi_opengl_tests | OpenGLTestFixture.* |
| RHI/D3D12/integration | d3d12_*_test | d3d12_minimal_test<br>d3d12_triangle_test<br>d3d12_quad_test<br>d3d12_sphere_test |
| RHI/OpenGL/integration | opengl_*_test | opengl_minimal_test<br>opengl_triangle_test<br>opengl_quad_test<br>opengl_sphere_test |
### 3.1 RHI 参数化测试说明
`tests/RHI/unit/` 使用 Google Test 参数化测试 (TEST_P)：
```cpp
// 使用 INSTANTIATE_TEST_SUITE_P 创建两个测试变体
INSTANTIATE_TEST_SUITE_P(D3D12, RHITestFixture, ::testing::Values(RHIType::D3D12));
INSTANTIATE_TEST_SUITE_P(OpenGL, RHITestFixture, ::testing::Values(RHIType::OpenGL));
// 测试名称格式: Suite/TestName/Instance
// 例如: D3D12/RHITestFixture.Buffer_Create/0
// OpenGL/RHITestFixture.Buffer_Create/0
```
**CTest 前缀说明**：
- `D3D12/` - D3D12 后端实例
- `OpenGL/` - OpenGL 后端实例
---
## 4. 测试用例命名
**格式**: `Component_Category_SubBehavior`
| 部分 | 说明 | 示例 |
| ----------- | -------- | ------------------------------------- |
| Component | 被测组件 | Memory, Buffer, Texture |
| Category | 操作类别 | Create, Get, Set, Map, Reset |
| SubBehavior | 具体行为 | DefaultHeap, GPUAddress, ValidPointer |
**示例**:
```
Buffer_Create_DefaultHeap
Texture_Create_2D
Fence_Signal_Wait
```
**禁止模式**:
- `*_Placeholder` - 无意义的占位测试
- 驼峰+下划线混用
---
## 5. CMake 规范
### 5.1 单元测试模板
```cmake
cmake_minimum_required(VERSION 3.15)
find_package(GTest REQUIRED)
set(TEST_SOURCES
test_module.cpp
)
add_executable(module_tests ${TEST_SOURCES})
if(MSVC)
set_target_properties(module_tests PROPERTIES
LINK_FLAGS "/NODEFAULTLIB:libcpmt.lib /NODEFAULTLIB:libcmt.lib"
)
endif()
target_link_libraries(module_tests PRIVATE
XCEngine
GTest::gtest
GTest::gtest_main
)
target_include_directories(module_tests PRIVATE
${CMAKE_SOURCE_DIR}/engine/include
${CMAKE_SOURCE_DIR}/tests/fixtures
)
include(GoogleTest)
gtest_discover_tests(module_tests)
```
### 5.2 RHI 测试 CMakeLists 模板
```cmake
cmake_minimum_required(VERSION 3.15)
project(rhi_backend_tests)
find_package(GTest REQUIRED)
find_package(Python3 REQUIRED) # 集成测试需要
# 单元测试
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)
```
---
## 6. 测试执行
### 6.1 增量构建（推荐）
**何时需要重新运行 `cmake ..`**：
- 新增/删除/重命名源文件
- 修改 CMakeLists.txt（添加 subdirectory、target 等）
- 修改编译器选项或宏定义
**增量构建命令**：
```bash
# 1. 增量配置（检测 CMakeLists.txt 变化）
cd build
cmake ..
# 2. 只构建特定 target（不重新配置整个项目）
cmake --build . --target math_tests --config Debug
# 3. 只构建特定模块
cmake --build . --target rhi_unit_tests --config Debug # RHI抽象层测试
cmake --build . --target rhi_d3d12_tests --config Debug # D3D12后端测试
cmake --build . --target rhi_opengl_tests --config Debug # OpenGL后端测试
cmake -S . -B build
```
### 6.2 完整构建
当以下内容发生变化时，需要重新执行配置：
- 新增或删除源文件
- 修改任意 `CMakeLists.txt`
- 修改 target、依赖、编译定义或测试发现方式
### 3.2 构建
```bash
cmake --build build --config Debug
cd build && ctest -C Debug --output-on-failure
```
### 6.3 测试运行
开发时优先增量构建单个 target，例如：
```bash
# 列出所有测试
ctest -N
# 运行所有测试
ctest -C Debug --output-on-failure
# 运行特定模块测试
ctest -R "^Math_" -C Debug --output-on-failure
# 运行 RHI 抽象层测试 (D3D12 + OpenGL 同时测试)
ctest -R "^D3D12/|^OpenGL/" -C Debug --output-on-failure
# 只运行 RHI 抽象层的 D3D12 后端测试
ctest -R "^D3D12/" -C Debug --output-on-failure
# 只运行 RHI 抽象层的 OpenGL 后端测试
ctest -R "^OpenGL/" -C Debug --output-on-failure
# 运行 D3D12 后端专用测试
ctest -R "D3D12TestFixture|SwapChainTestFixture" -C Debug --output-on-failure
# 运行 OpenGL 后端专用测试
ctest -R "OpenGLTestFixture" -C Debug --output-on-failure
# 运行特定测试用例
ctest -R "Buffer_Create" -C Debug --output-on-failure
# 运行 D3D12 集成测试
ctest -R "d3d12_minimal_test|d3d12_triangle_test|d3d12_quad_test|d3d12_sphere_test" -C Debug --output-on-failure
# 运行 OpenGL 集成测试
ctest -R "opengl_minimal_test|opengl_triangle_test|opengl_quad_test|opengl_sphere_test" -C Debug --output-on-failure
# 运行所有 RHI 测试 (单元 + 集成)
ctest -R "d3d12_|opengl_|D3D12/|OpenGL/" -C Debug --output-on-failure
cmake --build build --config Debug --target rhi_unit_tests
cmake --build build --config Debug --target rhi_integration_minimal
cmake --build build --config Debug --target rhi_integration_triangle
```
---
### 3.3 运行
## 7. 测试实现规范
### 7.1 单元测试结构
```cpp
#include <gtest/gtest.h>
#include <XCEngine/Module/Component.h>
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);
}
```
### 7.2 断言选择
| 断言 | 用途 |
| ---------- | ---------------------- |
| `ASSERT_*` | 致命错误，立即终止测试 |
| `EXPECT_*` | 非致命错误，继续执行 |
---
## 8. CI 配置
```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 模块构建和运行时间
| 模块 | 构建时间 | 运行时间 | 测试数量 |
| ------------------------ | -------- | -------- | --------------------- |
| math | ~6s | ~26s | 140 |
| Core | ~6s | ~4s | 25 |
| 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/Texture | ~4s | ~31s | 36 |
| Resources/Mesh | ~4s | ~31s | 29 |
| Resources/Material | ~4s | ~31s | 14 |
| Resources/Shader | ~4s | ~31s | 13 |
| Resources/AudioClip | ~4s | ~31s | 15 |
| input | ~4s | ~9s | 40 |
| RHI/unit (抽象层) | ~20s | ~60s | 138 (69×2后端) |
| RHI/integration (抽象层) | ~10s | ~20s | 2 (minimal×2后端) |
| D3D12 unit | ~3s | ~55s | 54 |
| OpenGL unit | ~46s | ~11s | 61 |
| D3D12 integration | ~10s | ~20s | 4 |
| OpenGL integration | ~60s | ~20s | 4 |
| **总计** | - | - | **860 (+1 disabled)** |
**注意**：
- RHI/unit 抽象层测试数量为 69 个用例，每个用例同时在 D3D12 和 OpenGL 两个后端上执行，共 138 次测试运行
- RHI/integration 抽象层集成测试验证 RHI 接口的渲染管线完整性，通过参数化同时测试两个后端
- 后端集成测试包含 minimal/triangle/quad/sphere 四个场景，每个后端各 4 个
- Resources 模块测试已按类型拆分到独立子目录中
### 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_texture_tests --config Debug
cmake --build . --target resources_mesh_tests --config Debug
cmake --build . --target resources_material_tests --config Debug
cmake --build . --target resources_shader_tests --config Debug
cmake --build . --target resources_audioclip_tests --config Debug
cmake --build . --target input_tests --config Debug
cmake --build . --target rhi_unit_tests --config Debug # RHI抽象层测试
cmake --build . --target rhi_d3d12_tests --config Debug
cmake --build . --target rhi_opengl_tests --config Debug
cmake --build . --target d3d12_minimal_test --config Debug # D3D12集成测试
cmake --build . --target d3d12_triangle_test --config Debug
cmake --build . --target d3d12_quad_test --config Debug
cmake --build . --target d3d12_sphere_test --config Debug
cmake --build . --target opengl_minimal_test --config Debug # OpenGL集成测试
cmake --build . --target opengl_triangle_test --config Debug
cmake --build . --target opengl_quad_test --config Debug
cmake --build . --target opengl_sphere_test --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 "Texture[A-Z]|Mesh[A-Z]|Shader[A-Z]|AudioClip[A-Z]|Material[A-Z]" -C Debug --output-on-failure
ctest -R "Input|WindowsInput" -C Debug --output-on-failure
ctest -R "^D3D12/|^OpenGL/" -C Debug --output-on-failure # RHI抽象层测试
ctest -R "D3D12TestFixture|SwapChainTestFixture" -C Debug --output-on-failure # D3D12后端测试
ctest -R "OpenGLTestFixture" -C Debug --output-on-failure # OpenGL后端测试
ctest -R "d3d12_minimal_test|d3d12_triangle_test|d3d12_quad_test|d3d12_sphere_test" -C Debug --output-on-failure # D3D12集成测试
ctest -R "opengl_minimal_test|opengl_triangle_test|opengl_quad_test|opengl_sphere_test" -C Debug --output-on-failure # OpenGL集成测试
ctest --test-dir build -N -C Debug
```
### 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_texture_tests --config Debug
cmake --build . --target resources_mesh_tests --config Debug
cmake --build . --target resources_material_tests --config Debug
cmake --build . --target resources_shader_tests --config Debug
cmake --build . --target resources_audioclip_tests --config Debug
cmake --build . --target input_tests --config Debug
ctest -R "Component_Test|TransformComponent_|^Scene_|Texture[A-Z]|Mesh[A-Z]|Shader[A-Z]|AudioClip[A-Z]|Material[A-Z]|Input|WindowsInput" -C Debug --output-on-failure
# ==================== RHI 模块 ====================
# RHI抽象层测试 (推荐优先测试，同时验证D3D12和OpenGL)
cmake --build . --target rhi_unit_tests --config Debug
ctest -R "^D3D12/|^OpenGL/" -C Debug --output-on-failure
# RHI后端专用测试 (验证特定后端实现)
cmake --build . --target rhi_d3d12_tests --config Debug
cmake --build . --target rhi_opengl_tests --config Debug
ctest -R "D3D12TestFixture|SwapChainTestFixture" -C Debug --output-on-failure
ctest -R "OpenGLTestFixture" -C Debug --output-on-failure
# RHI集成测试 (验证完整渲染管线)
cmake --build . --target d3d12_minimal_test --config Debug
cmake --build . --target d3d12_triangle_test --config Debug
cmake --build . --target d3d12_quad_test --config Debug
cmake --build . --target d3d12_sphere_test --config Debug
cmake --build . --target opengl_minimal_test --config Debug
cmake --build . --target opengl_triangle_test --config Debug
cmake --build . --target opengl_quad_test --config Debug
cmake --build . --target opengl_sphere_test --config Debug
ctest -R "d3d12_minimal_test|d3d12_triangle_test|d3d12_quad_test|d3d12_sphere_test" -C Debug --output-on-failure
ctest -R "opengl_minimal_test|opengl_triangle_test|opengl_quad_test|opengl_sphere_test" -C Debug --output-on-failure
ctest --test-dir build -C Debug --output-on-failure
```
### 9.4 注意事项
运行单个可执行测试也可以直接使用 gtest 过滤：
- **RHI/unit 抽象层测试**：运行时间~60s，138次测试（69用例×2后端）。推荐优先测试，可快速验证接口兼容性和跨平台一致性
- **OpenGL 后端测试**：构建时间较长(~46s)，因为需要编译 glad.c。建议单独构建
- **D3D12 后端测试**：运行时间较长(~55s)，适合 CI 自动化
- **RHI 集成测试**：需要 GPU 环境，渲染输出与基准 PPM 文件对比。OpenGL 构建时间较长因为需要编译 glad.c
- **Resources 模块**：运行时间~31s，包含大量资源加载测试
- **Math 模块**：运行时间~26s，包含140个数学运算测试
---
**最后更新**: 2026-03-25
---
## 附录 A. RHI 测试分层详解
### A.1 为什么需要五层测试？
RHI（Render Hardware Interface）抽象层测试的目的是确保：
1. **接口兼容性** - RHI定义的抽象接口在不同后端都能正常工作
2. **跨平台一致性** - 同样的代码逻辑在D3D12和OpenGL上行为一致
3. **后端实现正确性** - 各后端的封装实现符合RHI接口约定
4. **渲染管线完整性** - 多组件协作和完整渲染流程正确性
5. **RHI接口完整性** - RHI抽象层接口的渲染管线完整性验证
### A.2 五层测试的关系
```
┌─────────────────────────────────────────────────────────────┐
│ RHI 抽象层单元测试 (unit/) │
│ TEST_P: 一份代码，验证 D3D12/OpenGL 接口兼容 │
│ 实例: D3D12/RHITestFixture.* / OpenGL/RHITestFixture.* │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────┴───────────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ D3D12 后端单元测试 │ │ OpenGL 后端单元测试 │
│ (D3D12/unit/) │ │ (OpenGL/unit/) │
│ TEST_F: D3D12 专用 │ │ TEST_F: OpenGL 专用 │
│ 验证 D3D12 封装实现 │ │ 验证 OpenGL 封装实现 │
└─────────────────────────┘ └─────────────────────────┘
│
┌───────────────────┴───────────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ D3D12 集成测试 │ │ OpenGL 集成测试 │
│ (D3D12/integration/) │ │ (OpenGL/integration/) │
│ minimal/triangle/ │ │ minimal/triangle/ │
│ quad/sphere │ │ quad/sphere │
│ Python脚本对比PPM │ │ Python脚本对比PPM │
└─────────────────────────┘ └─────────────────────────┘
│
┌───────────────────┴───────────────────┐
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ RHI 抽象层集成测试 (integration/) │
│ TEST_P: 共享夹具，验证 D3D12/OpenGL 渲染管线 │
│ 实例: D3D12/MinimalTest.* / OpenGL/MinimalTest.* │
│ minimal: 最小渲染场景，Python脚本对比PPM │
└─────────────────────────────────────────────────────────────┘
```bash
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=D3D12/TriangleTest.RenderTriangle/0
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=OpenGL/TriangleTest.RenderTriangle/0
```
### A.3 测试执行建议
## 4. RHI 测试分层
| 场景 | 推荐测试 |
| ----------------------- | ------------------------------------------------------------------------ |
| 日常开发 (RHI 接口验证) | `rhi_unit_tests` |
| 验证 RHI 渲染管线 | `rhi_integration_minimal` |
| 开发 D3D12 后端 | `rhi_unit_tests` + `rhi_d3d12_tests` |
| 开发 OpenGL 后端 | `rhi_unit_tests` + `rhi_opengl_tests` |
| 验证渲染管线 | D3D12/OpenGL 后端集成测试 |
| CI 自动化 | `rhi_unit_tests` + `rhi_d3d12_tests` + `rhi_opengl_tests` + 后端集成测试 |
RHI 当前分成四类测试：
### A.4 可执行文件命名规范
| 层级 | 目录 | 目标 |
| --- | --- | --- |
| 抽象层单元测试 | `tests/RHI/unit/` | 验证公共 RHI 接口在 D3D12 / OpenGL 上的一致性 |
| 抽象层集成测试 | `tests/RHI/integration/` | 用同一套 RHI 抽象代码驱动两套后端完成真实渲染 |
| D3D12 后端测试 | `tests/RHI/D3D12/` | 验证 D3D12 封装本身 |
| OpenGL 后端测试 | `tests/RHI/OpenGL/` | 验证 OpenGL 封装本身 |
设计边界：
- `tests/RHI/unit/` 与 `tests/RHI/integration/` 只能依赖公共 RHI 抽象接口。
- 后端专有头文件、原生句柄、后端专用 helper，只允许出现在 `tests/RHI/D3D12/**` 与 `tests/RHI/OpenGL/**`。
- 如果抽象层测试为了通过而被迫引入后端 API，优先修 RHI 本身，而不是给测试开后门。
## 5. 当前 RHI Target
当前已经存在的主要 RHI target：
| 类别 | target |
| --- | --- |
| 抽象层单元测试 | `rhi_unit_tests` |
| 抽象层集成测试 | `rhi_integration_minimal` |
| 抽象层集成测试 | `rhi_integration_triangle` |
| D3D12 后端单元测试 | `rhi_d3d12_tests` |
| OpenGL 后端单元测试 | `rhi_opengl_tests` |
| D3D12 后端集成测试 | `d3d12_minimal_test` `d3d12_triangle_test` `d3d12_quad_test` `d3d12_sphere_test` |
| OpenGL 后端集成测试 | `opengl_minimal_test` `opengl_triangle_test` `opengl_quad_test` `opengl_sphere_test` |
说明：
- 抽象层集成测试目前只正式包含 `minimal` 与 `triangle`。
- `quad` 仍在向纯 RHI 抽象测试迁移中，未进入本列表。
## 6. RHI 抽象层集成测试规范
### 6.1 当前目录
```text
tests/RHI/integration/
├─ fixtures/
│ ├─ RHIIntegrationFixture.h
│ └─ RHIIntegrationFixture.cpp
├─ minimal/
│ ├─ CMakeLists.txt
│ ├─ GT.ppm
│ └─ main.cpp
├─ triangle/
│ ├─ CMakeLists.txt
│ ├─ GT.ppm
│ └─ main.cpp
├─ compare_ppm.py
└─ CMakeLists.txt
```
rhi_<层级>_tests
├── rhi_unit_tests # RHI抽象层单元测试
├── rhi_integration_minimal # RHI抽象层集成测试 (minimal)
├── rhi_d3d12_tests # D3D12后端封装测试
├── rhi_opengl_tests # OpenGL后端封装测试
└── <backend>_<scene>_test # 后端集成测试 (如 d3d12_minimal_test)
### 6.2 约束
抽象层集成测试必须满足以下规则：
1. 只包含公共 RHI 头文件与共享 fixture。
2. 同一个测试场景通过参数化方式同时跑 D3D12 和 OpenGL。
3. 每个场景目录只维护一张基准图：`GT.ppm`。
4. 截图输出允许按后端区分命名，例如：
- `minimal_d3d12.ppm`
- `minimal_opengl.ppm`
- `triangle_d3d12.ppm`
- `triangle_opengl.ppm`
5. 两个后端都必须与同一张 `GT.ppm` 做比对。
6. 新测试如果暴露抽象层缺口，应先补 RHI，再补测试。
### 6.3 命名
- 目录名：`tests/RHI/integration/<scene>/`
- target 名：`rhi_integration_<scene>`
- 截图名：`<scene>_d3d12.ppm` / `<scene>_opengl.ppm`
- 基准图名：固定为 `GT.ppm`
### 6.4 CMake 约定
每个抽象层集成测试目录都应：
- 使用独立 target
- 复用 `fixtures/RHIIntegrationFixture.cpp`
- 链接 `XCEngine`、`GTest::gtest` 以及当前两套后端所需系统库
- 在 `POST_BUILD` 中复制：
- `compare_ppm.py`
- 当前目录下的 `GT.ppm`
- 运行所需的 `renderdoc.dll`
- 使用 `gtest_discover_tests(...)`
### 6.5 推荐验证步骤
以 `triangle` 为例：
```bash
cmake -S . -B build
cmake --build build --config Debug --target rhi_integration_triangle
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=D3D12/TriangleTest.RenderTriangle/0
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=OpenGL/TriangleTest.RenderTriangle/0
```
通过标准：
- 两个后端都成功渲染
- 两个后端截图都能通过与同一张 `GT.ppm` 的比对
## 7. 新增一个 RHI 抽象层集成测试时
标准流程：
1. 在 `tests/RHI/integration/<scene>/` 新建 `main.cpp`、`CMakeLists.txt`、`GT.ppm`。
2. 在 `tests/RHI/integration/CMakeLists.txt` 中注册 `add_subdirectory(<scene>)`。
3. 先只用公共 RHI 接口完成最小可运行版本。
4. 分别验证 D3D12 / OpenGL。
5. 若失败源于抽象层能力不足，先修 RHI，再回到测试。
6. 确认双后端都通过后，再提交。
## 8. 文档维护要求
以下变化必须同步更新本文件：
- 测试目录结构变化
- 新增或删除测试 target
- RHI 抽象层集成测试场景变化
- 基准图管理规则变化
- 构建与运行命令变化
禁止继续在文档中保留“计划中但尚未落地”的内容，除非明确标注为未完成状态。