XCEngine/tests/TEST_SPEC.md

XCEngine 测试规范

最后更新：2026-03-25

1. 目标

本文件只描述当前工作区内已经存在并仍然有效的测试约定，重点覆盖：

• tests/ 的整体组织方式
• CMake / CTest 的基本用法
• RHI 模块的测试分层
• RHI 抽象层集成测试的当前规范

如果代码、目录结构或 target 名称发生变化，应优先更新本文件，而不是继续累积过时说明。

2. 顶层结构

tests/CMakeLists.txt 当前纳入的测试子目录如下：

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

说明：

• 实际磁盘上的大小写有历史遗留差异；在 Windows 下通常不影响构建。
• 新增测试模块时，必须同时补充对应目录下的 CMakeLists.txt，并在 tests/CMakeLists.txt 中注册。

3. 基本构建方式

推荐始终使用 CMake 驱动构建和测试，不再维护额外的手工脚本流程。

3.1 配置

cmake -S . -B build

当以下内容发生变化时，需要重新执行配置：

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

3.2 构建

cmake --build build --config Debug

开发时优先增量构建单个 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

3.3 运行

列出测试：

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

运行全部测试：

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

运行单个可执行测试也可以直接使用 gtest 过滤：

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

4. RHI 测试分层

RHI 当前分成四类测试：

层级	目录	目标
抽象层单元测试	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
抽象层集成测试	rhi_integration_quad
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。

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

6.1 当前目录

tests/RHI/integration/
├─ fixtures/
│  ├─ RHIIntegrationFixture.h
│  └─ RHIIntegrationFixture.cpp
├─ minimal/
│  ├─ CMakeLists.txt
│  ├─ GT.ppm
│  └─ main.cpp
├─ triangle/
│  ├─ CMakeLists.txt
│  ├─ GT.ppm
│  └─ main.cpp
├─ quad/
│  ├─ CMakeLists.txt
│  ├─ GT.ppm
│  └─ main.cpp
├─ compare_ppm.py
└─ CMakeLists.txt

6.2 约束

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

1. 只包含公共 RHI 头文件与共享 fixture。
2. 同一个测试场景通过参数化方式同时跑 D3D12 和 OpenGL。
3. 每个场景目录只维护一张基准图：GT.ppm。
4. 截图输出允许按后端区分命名，例如：
   • minimal_d3d12.ppm
   • minimal_opengl.ppm
   • triangle_d3d12.ppm
   • triangle_opengl.ppm
   • quad_d3d12.ppm
   • quad_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 为例：

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 抽象层集成测试场景变化
• 基准图管理规则变化
• 构建与运行命令变化

禁止继续在文档中保留“计划中但尚未落地”的内容，除非明确标注为未完成状态。