XCEngine/tests/TEST_SPEC.md

XCEngine 测试规范

最后更新：2026-03-27

1. 目标

本文档只描述当前仓库里已经存在、已经生效、并且应当长期维护的测试规范。

重点覆盖：

• tests/ 的整体组织方式
• CMake / CTest 的推荐使用方式
• RHI 模块测试的分层边界
• RHI 抽象层集成测试的当前约束

如果目录结构、target 名称、后端覆盖范围或 GT 图规则发生变化，必须同步更新本文档。

2. 顶层结构

tests/CMakeLists.txt 当前纳入的主要测试模块如下：

tests/
├─ math/
├─ core/
├─ containers/
├─ memory/
├─ threading/
├─ debug/
├─ components/
├─ scene/
├─ RHI/
├─ resources/
└─ input/

说明：

• 新增测试模块时，必须同时补充对应目录下的 CMakeLists.txt，并在 tests/CMakeLists.txt 中注册。
• 测试目录命名、target 命名、文档命名必须和实际仓库状态一致，不保留“计划中但未落地”的旧说明。

3. 基本构建方式

推荐始终使用 CMake 驱动构建与测试。

3.1 配置

cmake -S . -B build

以下场景需要重新配置：

• 新增或删除源文件
• 修改任意 CMakeLists.txt
• 修改 target、依赖、编译定义或测试发现方式

3.2 增量构建

cmake --build build --config Debug

常用 RHI 聚合 target：

cmake --build build --config Debug --target rhi_abstraction_tests
cmake --build build --config Debug --target rhi_backend_tests
cmake --build build --config Debug --target rhi_all_tests

常用单项 target：

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
cmake --build build --config Debug --target rhi_integration_quad
cmake --build build --config Debug --target rhi_integration_sphere
cmake --build build --config Debug --target rhi_integration_backpack

3.3 运行

列出测试：

ctest --test-dir build -N -C Debug

运行全部测试：

ctest --test-dir build -C Debug --output-on-failure

直接运行 gtest 可执行文件也是合法入口。例如：

build\tests\RHI\unit\Debug\rhi_unit_tests.exe --gtest_brief=1
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=Vulkan/TriangleTest.RenderTriangle/0
build\tests\RHI\integration\backpack\Debug\rhi_integration_backpack.exe --gtest_filter=D3D12/BackpackTest.RenderBackpack/0

4. RHI 测试分层

RHI 当前分为四层测试：

层级	目录 / target	目标
抽象层单元测试	tests/RHI/unit/ / rhi_unit_tests	验证公共 RHI 接口在 D3D12 / OpenGL / Vulkan 上的统一语义
抽象层集成测试	tests/RHI/integration/ / rhi_integration_*	用同一套 RHI 抽象代码驱动三后端完成真实渲染并做 GT 图比对
D3D12 后端测试	tests/RHI/D3D12/	验证 D3D12 封装本身
OpenGL 后端测试	tests/RHI/OpenGL/	验证 OpenGL 封装本身
Vulkan 后端测试	tests/RHI/Vulkan/	验证 Vulkan 封装本身

补充说明：

• Vulkan 现在已经拥有独立的 tests/RHI/Vulkan/ 子树。
• tests/RHI/unit/ 继续只保留三后端参数化的抽象层统一语义测试。
• Vulkan 专属断言、原生句柄检查与直接依赖 Vulkan API 的测试，统一收敛到 tests/RHI/Vulkan/unit/。
• Vulkan 现在已经建立独立的后端 integration 子树，当前已覆盖 tests/RHI/Vulkan/integration/minimal/、triangle/、quad/、sphere/。
• Vulkan 后端后续仍可继续补更复杂的 backend integration，但不应再回流到 abstraction suite。

设计边界：

• tests/RHI/unit/ 与 tests/RHI/integration/ 只能依赖公共 RHI 抽象接口。
• 后端私有头文件、原生句柄、后端专用 helper，只允许出现在对应后端目录。
• 如果抽象层测试为了通过而被迫引入后端 API，优先修 RHI 本身，而不是给测试开后门。

5. 当前 RHI Target

5.1 抽象层

类别	target
抽象层单元测试	rhi_unit_tests
抽象层集成测试	rhi_integration_minimal
抽象层集成测试	rhi_integration_triangle
抽象层集成测试	rhi_integration_quad
抽象层集成测试	rhi_integration_sphere
抽象层集成测试	rhi_integration_backpack

5.2 后端专用

类别	target
D3D12 后端单元测试	rhi_d3d12_tests
OpenGL 后端单元测试	rhi_opengl_tests
Vulkan 后端单元测试	rhi_vulkan_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
Vulkan 后端集成测试	vulkan_minimal_test vulkan_triangle_test vulkan_quad_test vulkan_sphere_test

5.3 聚合 target

类别	target
抽象层单测聚合	rhi_abstraction_unit_tests
抽象层集成聚合	rhi_abstraction_integration_tests
抽象层总聚合	rhi_abstraction_tests
后端单测聚合	rhi_backend_unit_tests
Vulkan 后端聚合	rhi_vulkan_backend_tests
后端集成聚合	rhi_backend_integration_tests
后端总聚合	rhi_backend_tests
RHI 全量聚合	rhi_all_tests

6. RHI 抽象层集成测试规范

6.1 当前目录

tests/RHI/integration/
├─ fixtures/
│  ├─ RHIIntegrationFixture.h
│  └─ RHIIntegrationFixture.cpp
├─ minimal/
├─ triangle/
├─ quad/
├─ sphere/
├─ backpack/
├─ compare_ppm.py
├─ run_integration_test.py
├─ README.md
└─ CMakeLists.txt

6.2 当前场景

场景	目标
minimal	验证清屏、present、截图与 GT 比对链路
triangle	验证最小图形管线与顶点输入
quad	验证纹理采样与基础贴图渲染
sphere	验证更复杂顶点布局、纹理与 firstSet != 0 的描述符绑定路径
backpack	验证真实模型、资源导入结果与完整 draw path

6.3 统一约束

抽象层集成测试必须满足以下规则：

1. 只包含公共 RHI 头文件与共享 fixture。
2. 同一场景通过参数化方式同时运行 D3D12 / OpenGL / Vulkan。
3. 每个场景目录只维护一张基准图：GT.ppm。
4. 运行时截图允许按后端区分命名，例如：
   • minimal_d3d12.ppm
   • minimal_opengl.ppm
   • minimal_vulkan.ppm
5. 所有后端都必须与同一张 GT.ppm 做比对。
6. 新场景如果暴露抽象层缺口，应先补 RHI，再补测试。
7. sphere 必须继续保留对 firstSet != 0 绑定路径的覆盖，避免“忽略 set 语义也误通过”的假阳性。
8. backpack 是当前抽象层最接近真实资源渲染的场景，后续新增复杂渲染场景时不应削弱它的回归价值。

6.4 CMake 约束

每个抽象层集成测试目录都应：

• 使用独立 target
• 复用 fixtures/RHIIntegrationFixture.cpp
• 链接 XCEngine、GTest::gtest
• 在需要时按后端条件加入对应系统库
• 在 POST_BUILD 中复制：
  • compare_ppm.py
  • 当前场景的 GT.ppm
  • 运行所需的资源文件
• 使用 gtest_discover_tests(...)

6.5 推荐验证方式

cmake --build build --config Debug --target rhi_abstraction_integration_tests

build\tests\RHI\integration\minimal\Debug\rhi_integration_minimal.exe --gtest_filter=Vulkan/MinimalTest.RenderClear/0
build\tests\RHI\integration\triangle\Debug\rhi_integration_triangle.exe --gtest_filter=D3D12/TriangleTest.RenderTriangle/0
build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=OpenGL/QuadTest.RenderQuad/0
build\tests\RHI\integration\backpack\Debug\rhi_integration_backpack.exe --gtest_filter=Vulkan/BackpackTest.RenderBackpack/0

通过标准：

• 渲染成功
• 截图成功
• 与当前场景 GT.ppm 比对通过

7. 当前体系的完成度与后续方向

当前状态可以认为是“高完成度、可作为正式基线”，但不是“完全封顶”。

已经完成：

• 抽象层单测正式纳入 D3D12 / OpenGL / Vulkan
• 抽象层集成测试已经具备 5 个真实渲染场景
• GT 图回归链路已经稳定工作
• D3D12 与 OpenGL 仍保留独立后端测试树

仍需继续完善：

• 继续补更工程化的 Vulkan 后端 integration 场景覆盖
• 把仍然合理存在的后端专属断言与 skip 场景继续收敛
• 补充 resize / swapchain 重建 / 长时间 soak / 多线程录制 / validation layer 负例 等更工程化的测试
• 保持文档、CMake target 与实际测试状态同步

8. 文档维护要求

以下变化必须同步更新本文档：

• 测试目录结构变化
• 新增或删除测试 target
• 抽象层集成测试场景变化
• GT 图管理规则变化
• CMake 聚合入口变化
• 后端覆盖范围变化

禁止继续保留和当前仓库状态不一致的旧说明。