From d1b7fda8168c5215c003e3ad2f1860bfd7bf1e22 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Wed, 25 Mar 2026 18:59:40 +0800
Subject: [PATCH] docs: Update TEST_SPEC.md with RHI integration tests
documentation
- Add integration test directory structure
- Expand test hierarchy from 3 to 4 layers (add integration tests)
- Update module naming table with integration test executables
- Add integration test execution commands
- Add integration test performance references
- Update appendix A with 4-layer architecture diagram
- Update total test count to 860
---
tests/TEST_SPEC.md | 94 ++++++++++++++++++++++++++++++++++++----------
1 file changed, 74 insertions(+), 20 deletions(-)
diff --git a/tests/TEST_SPEC.md b/tests/TEST_SPEC.md
index 3e93c479..3a301c7a 100644
--- a/tests/TEST_SPEC.md
+++ b/tests/TEST_SPEC.md
@@ -65,7 +65,7 @@ tests/
├── scene/ # 场景测试
├── components/ # 组件测试
└── rhi/
- ├── CMakeLists.txt # RHI 测试主 CMake (包含 D3D12/OpenGL/unit)
+ ├── CMakeLists.txt # RHI 测试主 CMake (包含 D3D12/OpenGL/unit/integration)
├── unit/ # RHI 抽象层单元测试 (参数化, 同时测 D3D12/OpenGL)
│ ├── CMakeLists.txt
│ ├── fixtures/
@@ -81,24 +81,26 @@ tests/
├── unit/ # OpenGL 单元测试
│ ├── fixtures/
│ └── test_*.cpp
- └── integration/ # OpenGL 集成测试
+ └── integration/ # OpenGL 集成测试 (minimal/triangle/quad/sphere)
```
**注意**：Windows 文件系统大小写不敏感，`tests/Core/` 和 `tests/core/` 为同一目录。实际文件位于 `tests/core/`（小写），但 CMakeLists.txt 中配置为 `tests/Core/`（大写）。
### 2.1 RHI 测试分层架构
-RHI 测试分为三个层次，各层测试目标不同：
+RHI 测试分为四个层次，各层测试目标不同：
| 层次 | 位置 | 测试目标 | 测试方式 |
|------|------|----------|----------|
| **RHI抽象层** | `tests/RHI/unit/` | RHI接口定义、跨平台抽象、后端选择 | 参数化测试 (TEST_P)，一份代码同时测试 D3D12/OpenGL |
-| **D3D12后端封装** | `tests/RHI/D3D12/unit/` | D3D12 API封装实现 | 非参数化测试 (TEST_F)，直接测试D3D12封装 |
-| **OpenGL后端封装** | `tests/RHI/OpenGL/unit/` | OpenGL API封装实现 | 非参数化测试 (TEST_F)，直接测试OpenGL封装 |
+| **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文件 |
-**注意**：三层测试不是冗余，而是测试不同层次的封装。各层测试可以验证：
+**注意**：四层测试不是冗余，而是测试不同层次的封装。各层测试可以验证：
- RHI抽象层测试验证接口兼容性和跨平台一致性
- 后端专用测试验证各后端实现的正确性
+- 集成测试验证完整渲染管线和多组件协作
---
@@ -121,8 +123,10 @@ RHI 测试分为三个层次，各层测试目标不同：
| scene | scene_tests | Scene*/SceneManager_* |
| components | components_tests | Component_*|TransformComponent_* |
| RHI/unit (抽象层) | rhi_unit_tests | D3D12/RHITestFixture.*
OpenGL/RHITestFixture.* |
-| RHI/D3D12 (后端) | rhi_d3d12_tests | D3D12TestFixture.*
SwapChainTestFixture.* |
-| RHI/OpenGL (后端) | rhi_opengl_tests | OpenGLTestFixture.* |
+| 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 参数化测试说明
@@ -305,6 +309,15 @@ 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
```
---
@@ -382,9 +395,14 @@ jobs:
| RHI/unit (抽象层) | ~20s | ~60s | 138 (69×2后端) |
| D3D12 unit | ~3s | ~55s | 54 |
| OpenGL unit | ~46s | ~11s | 61 |
-| **总计** | - | - | **852 (+1 disabled)** |
+| D3D12 integration | ~10s | ~20s | 4 |
+| OpenGL integration | ~60s | ~20s | 4 |
+| **总计** | - | - | **860 (+1 disabled)** |
-**注意**：RHI/unit 抽象层测试数量为 69 个用例，每个用例同时在 D3D12 和 OpenGL 两个后端上执行，共 138 次测试运行。Resources 模块测试已按类型拆分到独立子目录中。
+**注意**：
+- RHI/unit 抽象层测试数量为 69 个用例，每个用例同时在 D3D12 和 OpenGL 两个后端上执行，共 138 次测试运行
+- 集成测试包含 minimal/triangle/quad/sphere 四个场景，每个后端各 4 个
+- Resources 模块测试已按类型拆分到独立子目录中
### 9.2 分模块构建命令（推荐）
@@ -409,6 +427,14 @@ 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
@@ -424,6 +450,8 @@ 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 按功能组构建和运行
@@ -462,6 +490,18 @@ 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 注意事项
@@ -469,25 +509,27 @@ ctest -R "OpenGLTestFixture" -C Debug --output-on-failure
- **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-24
+**最后更新**: 2026-03-25
---
## 附录 A. RHI 测试分层详解
-### A.1 为什么需要三层测试？
+### A.1 为什么需要四层测试？
RHI（Render Hardware Interface）抽象层测试的目的是确保：
1. **接口兼容性** - RHI定义的抽象接口在不同后端都能正常工作
2. **跨平台一致性** - 同样的代码逻辑在D3D12和OpenGL上行为一致
3. **后端实现正确性** - 各后端的封装实现符合RHI接口约定
+4. **渲染管线完整性** - 多组件协作和完整渲染流程正确性
-### A.2 三层测试的关系
+### A.2 四层测试的关系
```
┌─────────────────────────────────────────────────────────────┐
@@ -495,14 +537,24 @@ RHI（Render Hardware Interface）抽象层测试的目的是确保：
│ 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 │
└─────────────────────────┘ └─────────────────────────┘
```
@@ -513,13 +565,15 @@ RHI（Render Hardware Interface）抽象层测试的目的是确保：
| 日常开发 (RHI 接口验证) | `rhi_unit_tests` |
| 开发 D3D12 后端 | `rhi_unit_tests` + `rhi_d3d12_tests` |
| 开发 OpenGL 后端 | `rhi_unit_tests` + `rhi_opengl_tests` |
-| CI 自动化 | `rhi_unit_tests` + `rhi_d3d12_tests` + `rhi_opengl_tests` |
+| 验证渲染管线 | D3D12/OpenGL 集成测试 |
+| CI 自动化 | `rhi_unit_tests` + `rhi_d3d12_tests` + `rhi_opengl_tests` + 集成测试 |
### A.4 可执行文件命名规范
```
rhi_<层级>_tests
-├── rhi_unit_tests # RHI抽象层测试
-├── rhi_d3d12_tests # D3D12后端封装测试
-└── rhi_opengl_tests # OpenGL后端封装测试
+├── rhi_unit_tests # RHI抽象层测试
+├── rhi_d3d12_tests # D3D12后端封装测试
+├── rhi_opengl_tests # OpenGL后端封装测试
+└── __test # 集成测试 (如 d3d12_minimal_test)
```