From 83cd2fa591483cc2e9f8c66a1ceed4c930c8ec38 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Wed, 25 Mar 2026 23:41:45 +0800 Subject: [PATCH] Refresh test spec and align minimal shared GT --- tests/RHI/integration/minimal/CMakeLists.txt | 2 +- tests/TEST_SPEC.md | 736 +++++-------------- 2 files changed, 178 insertions(+), 560 deletions(-) diff --git a/tests/RHI/integration/minimal/CMakeLists.txt b/tests/RHI/integration/minimal/CMakeLists.txt index d3a1f563..7f0ee22a 100644 --- a/tests/RHI/integration/minimal/CMakeLists.txt +++ b/tests/RHI/integration/minimal/CMakeLists.txt @@ -45,7 +45,7 @@ add_custom_command(TARGET rhi_integration_minimal POST_BUILD ${CMAKE_SOURCE_DIR}/tests/RHI/integration/compare_ppm.py $/ COMMAND ${CMAKE_COMMAND} -E copy_if_different - ${CMAKE_SOURCE_DIR}/tests/RHI/D3D12/integration/minimal/GT.ppm + ${CMAKE_CURRENT_SOURCE_DIR}/GT.ppm $/GT.ppm COMMAND ${CMAKE_COMMAND} -E copy_if_different ${ENGINE_ROOT_DIR}/third_party/renderdoc/renderdoc.dll diff --git a/tests/TEST_SPEC.md b/tests/TEST_SPEC.md index 1aa97a3a..54a45e8e 100644 --- a/tests/TEST_SPEC.md +++ b/tests/TEST_SPEC.md @@ -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.*
OpenGL/RHITestFixture.* | -| RHI/integration (抽象层集成) | rhi_integration_minimal | D3D12/MinimalTest.*
OpenGL/MinimalTest.* | -| RHI/D3D12/unit (后端) | rhi_d3d12_tests | D3D12TestFixture.*
SwapChainTestFixture.* | -| RHI/OpenGL/unit (后端) | rhi_opengl_tests | OpenGLTestFixture.* | -| RHI/D3D12/integration | d3d12_*_test | d3d12_minimal_test
d3d12_triangle_test
d3d12_quad_test
d3d12_sphere_test | -| RHI/OpenGL/integration | opengl_*_test | opengl_minimal_test
opengl_triangle_test
opengl_quad_test
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 -#include - -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后端封装测试 -└── __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//` +- target 名：`rhi_integration_` +- 截图名：`_d3d12.ppm` / `_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//` 新建 `main.cpp`、`CMakeLists.txt`、`GT.ppm`。 +2. 在 `tests/RHI/integration/CMakeLists.txt` 中注册 `add_subdirectory()`。 +3. 先只用公共 RHI 接口完成最小可运行版本。 +4. 分别验证 D3D12 / OpenGL。 +5. 若失败源于抽象层能力不足，先修 RHI，再回到测试。 +6. 确认双后端都通过后，再提交。 + +## 8. 文档维护要求 + +以下变化必须同步更新本文件： + +- 测试目录结构变化 +- 新增或删除测试 target +- RHI 抽象层集成测试场景变化 +- 基准图管理规则变化 +- 构建与运行命令变化 + +禁止继续在文档中保留“计划中但尚未落地”的内容，除非明确标注为未完成状态。