XCEngine/tests/TEST_SPEC.md

# XCEngine 测试规范

最后更新：2026-03-25

## 1. 目标

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

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

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

## 2. 顶层结构

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

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

说明：

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

## 3. 基本构建方式

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

### 3.1 配置

```bash
cmake -S . -B build
```

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

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

### 3.2 构建

```bash
cmake --build build --config Debug
```

开发时优先增量构建单个 target，例如：

```bash
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 运行

列出测试：

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

运行全部测试：

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

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

```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
```

## 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 当前目录

```text
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` 为例：

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

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