Refresh test spec and align minimal shared GT
This commit is contained in:
@@ -45,7 +45,7 @@ add_custom_command(TARGET rhi_integration_minimal POST_BUILD
|
|||||||
${CMAKE_SOURCE_DIR}/tests/RHI/integration/compare_ppm.py
|
${CMAKE_SOURCE_DIR}/tests/RHI/integration/compare_ppm.py
|
||||||
$<TARGET_FILE_DIR:rhi_integration_minimal>/
|
$<TARGET_FILE_DIR:rhi_integration_minimal>/
|
||||||
COMMAND ${CMAKE_COMMAND} -E copy_if_different
|
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
|
$<TARGET_FILE_DIR:rhi_integration_minimal>/GT.ppm
|
||||||
COMMAND ${CMAKE_COMMAND} -E copy_if_different
|
COMMAND ${CMAKE_COMMAND} -E copy_if_different
|
||||||
${ENGINE_ROOT_DIR}/third_party/renderdoc/renderdoc.dll
|
${ENGINE_ROOT_DIR}/third_party/renderdoc/renderdoc.dll
|
||||||
|
|||||||
@@ -1,602 +1,220 @@
|
|||||||
# XCEngine 测试规范
|
# XCEngine 测试规范
|
||||||
|
|
||||||
## 1. 测试框架
|
最后更新：2026-03-25
|
||||||
|
|
||||||
| 组件 | 用途 |
|
## 1. 目标
|
||||||
| ----------- | -------------------- |
|
|
||||||
| Google Test | 单元测试框架 |
|
|
||||||
| CTest | CMake 测试发现和执行 |
|
|
||||||
|
|
||||||
---
|
本文件只描述当前工作区内已经存在并仍然有效的测试约定，重点覆盖：
|
||||||
|
|
||||||
## 2. 测试目录结构
|
- `tests/` 的整体组织方式
|
||||||
|
- CMake / CTest 的基本用法
|
||||||
|
- RHI 模块的测试分层
|
||||||
|
- RHI 抽象层集成测试的当前规范
|
||||||
|
|
||||||
```
|
如果代码、目录结构或 target 名称发生变化，应优先更新本文件，而不是继续累积过时说明。
|
||||||
|
|
||||||
|
## 2. 顶层结构
|
||||||
|
|
||||||
|
`tests/CMakeLists.txt` 当前纳入的测试子目录如下：
|
||||||
|
|
||||||
|
```text
|
||||||
tests/
|
tests/
|
||||||
├── CMakeLists.txt # 主 CMake 配置 (包含 enable_testing)
|
├─ math/
|
||||||
├── fixtures/ # 共享测试夹具
|
├─ core/
|
||||||
├── math/ # 数学库测试
|
├─ containers/
|
||||||
├── Core/ # 核心库测试
|
├─ memory/
|
||||||
│ ├── CMakeLists.txt
|
├─ threading/
|
||||||
│ ├── Asset/ # Core/Asset 模块测试
|
├─ debug/
|
||||||
│ │ ├── CMakeLists.txt
|
├─ components/
|
||||||
│ │ ├── test_iresource.cpp
|
├─ scene/
|
||||||
│ │ ├── test_resource_types.cpp
|
├─ rhi/
|
||||||
│ │ ├── test_resource_guid.cpp
|
├─ resources/
|
||||||
│ │ ├── test_resource_handle.cpp
|
└─ input/
|
||||||
│ │ ├── 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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**注意**：Windows 文件系统大小写不敏感，`tests/Core/` 和 `tests/core/` 为同一目录。实际文件位于 `tests/core/`（小写），但 CMakeLists.txt 中配置为 `tests/Core/`（大写）。
|
说明：
|
||||||
|
|
||||||
### 2.1 RHI 测试分层架构
|
- 实际磁盘上的大小写有历史遗留差异；在 Windows 下通常不影响构建。
|
||||||
|
- 新增测试模块时，必须同时补充对应目录下的 `CMakeLists.txt`，并在 `tests/CMakeLists.txt` 中注册。
|
||||||
|
|
||||||
RHI 测试分为五个层次，各层测试目标不同：
|
## 3. 基本构建方式
|
||||||
|
|
||||||
| 层次 | 位置 | 测试目标 | 测试方式 |
|
推荐始终使用 CMake 驱动构建和测试，不再维护额外的手工脚本流程。
|
||||||
| ------------------ | -------------------------- | --------------------------------- | ------------------------------------------------------------------- |
|
|
||||||
| **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文件 |
|
|
||||||
|
|
||||||
**注意**：五层测试不是冗余，而是测试不同层次的封装。各层测试可以验证：
|
### 3.1 配置
|
||||||
- RHI抽象层单元测试验证接口兼容性和跨平台一致性
|
|
||||||
- RHI抽象层集成测试验证RHI接口的渲染管线完整性
|
|
||||||
- 后端专用测试验证各后端实现的正确性
|
|
||||||
- 后端集成测试验证完整渲染管线和多组件协作
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
# 1. 增量配置（检测 CMakeLists.txt 变化）
|
cmake -S . -B build
|
||||||
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后端测试
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 6.2 完整构建
|
当以下内容发生变化时，需要重新执行配置：
|
||||||
|
|
||||||
|
- 新增或删除源文件
|
||||||
|
- 修改任意 `CMakeLists.txt`
|
||||||
|
- 修改 target、依赖、编译定义或测试发现方式
|
||||||
|
|
||||||
|
### 3.2 构建
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cmake --build build --config Debug
|
cmake --build build --config Debug
|
||||||
cd build && ctest -C Debug --output-on-failure
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 6.3 测试运行
|
开发时优先增量构建单个 target，例如：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 列出所有测试
|
cmake --build build --config Debug --target rhi_unit_tests
|
||||||
ctest -N
|
cmake --build build --config Debug --target rhi_integration_minimal
|
||||||
|
cmake --build build --config Debug --target rhi_integration_triangle
|
||||||
# 运行所有测试
|
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### 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
|
```bash
|
||||||
# ==================== 快速开发工作流 ====================
|
ctest --test-dir build -N -C Debug
|
||||||
|
|
||||||
# 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集成测试
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 9.3 按功能组构建和运行
|
运行全部测试：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# ==================== 基础设施模块 ====================
|
ctest --test-dir build -C Debug --output-on-failure
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 9.4 注意事项
|
运行单个可执行测试也可以直接使用 gtest 过滤：
|
||||||
|
|
||||||
- **RHI/unit 抽象层测试**：运行时间~60s，138次测试（69用例×2后端）。推荐优先测试，可快速验证接口兼容性和跨平台一致性
|
```bash
|
||||||
- **OpenGL 后端测试**：构建时间较长(~46s)，因为需要编译 glad.c。建议单独构建
|
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=D3D12/TriangleTest.RenderTriangle/0
|
||||||
- **D3D12 后端测试**：运行时间较长(~55s)，适合 CI 自动化
|
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=OpenGL/TriangleTest.RenderTriangle/0
|
||||||
- **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 │
|
|
||||||
└─────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### A.3 测试执行建议
|
## 4. RHI 测试分层
|
||||||
|
|
||||||
| 场景 | 推荐测试 |
|
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` + 后端集成测试 |
|
|
||||||
|
|
||||||
### 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抽象层单元测试
|
### 6.2 约束
|
||||||
├── rhi_integration_minimal # RHI抽象层集成测试 (minimal)
|
|
||||||
├── rhi_d3d12_tests # D3D12后端封装测试
|
抽象层集成测试必须满足以下规则：
|
||||||
├── rhi_opengl_tests # OpenGL后端封装测试
|
|
||||||
└── <backend>_<scene>_test # 后端集成测试 (如 d3d12_minimal_test)
|
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 抽象层集成测试场景变化
|
||||||
|
- 基准图管理规则变化
|
||||||
|
- 构建与运行命令变化
|
||||||
|
|
||||||
|
禁止继续在文档中保留“计划中但尚未落地”的内容，除非明确标注为未完成状态。
|
||||||
|
|||||||
Reference in New Issue
Block a user