342 lines
10 KiB
Markdown
342 lines
10 KiB
Markdown
# XCEngine 测试规范
|
||
|
||
最后更新：`2026-04-04`
|
||
|
||
## 1. 目标
|
||
|
||
本文档描述当前仓库里已经落地、已经生效、并且应当长期维护的测试基线。
|
||
|
||
重点覆盖：
|
||
|
||
- `tests/` 的真实目录结构
|
||
- 当前 CMake / CTest 入口
|
||
- RHI 测试分层边界
|
||
- Rendering / Editor / Scripting 相关聚合 target
|
||
|
||
如果目录结构、target 名称、场景覆盖范围或回归入口变化，必须同步更新本文档。
|
||
|
||
## 2. 顶层结构
|
||
|
||
`tests/CMakeLists.txt` 当前纳入的主模块如下：
|
||
|
||
```text
|
||
tests/
|
||
├─ Components/
|
||
├─ Core/
|
||
│ ├─ Asset/
|
||
│ ├─ Containers/
|
||
│ ├─ IO/
|
||
│ └─ Math/
|
||
├─ Debug/
|
||
├─ Editor/
|
||
├─ Fixtures/
|
||
├─ Input/
|
||
├─ Memory/
|
||
├─ Rendering/
|
||
│ ├─ integration/
|
||
│ └─ unit/
|
||
├─ Resources/
|
||
│ ├─ AudioClip/
|
||
│ ├─ Material/
|
||
│ ├─ Mesh/
|
||
│ ├─ Shader/
|
||
│ └─ Texture/
|
||
├─ RHI/
|
||
│ ├─ D3D12/
|
||
│ ├─ integration/
|
||
│ ├─ OpenGL/
|
||
│ ├─ unit/
|
||
│ └─ Vulkan/
|
||
├─ Scene/
|
||
├─ Scripting/
|
||
└─ Threading/
|
||
```
|
||
|
||
说明：
|
||
|
||
- 新增测试模块时，必须同时补对应目录下的 `CMakeLists.txt`，并在 `tests/CMakeLists.txt` 注册。
|
||
- 目录名、target 名、文档说明必须与当前 checkout 一致，不保留“计划中但未落地”的旧描述。
|
||
|
||
## 3. 基本构建方式
|
||
|
||
推荐始终使用 CMake 驱动构建与测试。
|
||
|
||
### 3.1 配置
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64
|
||
```
|
||
|
||
如果当前任务不需要 Mono：
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
|
||
```
|
||
|
||
以下情况需要重新配置：
|
||
|
||
- 新增或删除源文件
|
||
- 修改任意 `CMakeLists.txt`
|
||
- 修改 target、依赖、编译定义、测试发现方式
|
||
|
||
### 3.2 通用入口
|
||
|
||
```bash
|
||
cmake --build build --config Debug
|
||
ctest --test-dir build -N -C Debug
|
||
ctest --test-dir build -C Debug --output-on-failure
|
||
```
|
||
|
||
## 4. 当前主要 target
|
||
|
||
### 4.1 Engine 基础模块
|
||
|
||
| 模块 | target |
|
||
| --- | --- |
|
||
| Core | `core_tests` |
|
||
| Core/Asset | `asset_tests` |
|
||
| Core/Containers | `containers_tests` |
|
||
| Core/IO | `io_tests` |
|
||
| Core/Math | `math_tests` |
|
||
| Memory | `memory_tests` |
|
||
| Threading | `threading_tests` |
|
||
| Debug | `debug_tests` |
|
||
| Components | `components_tests` |
|
||
| Scene | `scene_tests` |
|
||
| Input | `input_tests` |
|
||
|
||
### 4.2 Resources
|
||
|
||
| 模块 | target |
|
||
| --- | --- |
|
||
| AudioClip | `audioclip_tests` |
|
||
| Material | `material_tests` |
|
||
| Mesh | `mesh_tests` |
|
||
| Shader | `shader_tests` |
|
||
| Texture | `texture_tests` |
|
||
|
||
这些测试当前不只是验证简单 loader，还会覆盖：
|
||
|
||
- `AssetDatabase`
|
||
- `.meta`
|
||
- `Library/SourceAssetDB`
|
||
- `Library/ArtifactDB`
|
||
- artifact 重导入逻辑
|
||
|
||
### 4.3 Editor / Scripting
|
||
|
||
| 模块 | target |
|
||
| --- | --- |
|
||
| Editor | `editor_tests` |
|
||
| Scripting | `scripting_tests` |
|
||
|
||
补充说明：
|
||
|
||
- `editor_tests` 当前覆盖 action routing、application asset cache stub、editor console sink、script assembly builder、play session，以及一整套 viewport helper 链。
|
||
- 当前 viewport 相关覆盖至少包括：
|
||
- `SceneViewportChrome`
|
||
- `SceneViewportInteractionFrame`
|
||
- `SceneViewportNavigation`
|
||
- `SceneViewportInteractionActions`
|
||
- `SceneViewportInteractionResolver`
|
||
- `SceneViewportTransformGizmoCoordinator`
|
||
- `SceneViewportOverlayFrameCache`
|
||
- `SceneViewportOverlayProviders`
|
||
- `SceneViewportOverlaySpriteResources`
|
||
- `SceneViewportShaderPaths`
|
||
- `ViewportHostRenderFlowUtils`
|
||
- `ViewportHostRenderTargets`
|
||
- `ViewportHostSurfaceUtils`
|
||
- `ViewportObjectIdPicker`
|
||
- `test_scene_viewport_overlay_renderer.cpp` 这个测试文件名仍保留历史命名，但当前主要锚定的是 viewport math、HUD overlay 和 infinite-grid 参数 helper；它不意味着仓库里仍存在 `SceneViewportOverlayRenderer.*` 源文件。
|
||
- `test_play_session_controller_scripting.cpp` 只会在启用 Mono 且 `xcengine_managed_assemblies` 可用时加入 `editor_tests`。
|
||
- `scripting_tests` 在启用 Mono 时会补入 `test_mono_script_runtime.cpp`。
|
||
- 如果存在 `xcengine_test_project_managed_assemblies` target，`scripting_tests` 还会补入 `test_project_script_assembly.cpp`，并使用测试专用的项目脚本程序集输出目录，而不是直接复用 `project/Library/ScriptAssemblies/`。
|
||
|
||
### 4.4 Rendering
|
||
|
||
| 类别 | target |
|
||
| --- | --- |
|
||
| 单元测试 | `rendering_unit_tests` |
|
||
| 单测聚合 | `rendering_unit_test_targets` |
|
||
| 集成聚合 | `rendering_integration_tests` |
|
||
| 全量聚合 | `rendering_all_tests` |
|
||
| 阶段回归 | `rendering_phase_regression` |
|
||
|
||
当前 rendering integration targets：
|
||
|
||
- `rendering_integration_textured_quad_scene`
|
||
- `rendering_integration_unlit_scene`
|
||
- `rendering_integration_object_id_scene`
|
||
- `rendering_integration_directional_shadow_scene`
|
||
- `rendering_integration_backpack_scene`
|
||
- `rendering_integration_backpack_lit_scene`
|
||
- `rendering_integration_camera_stack_scene`
|
||
- `rendering_integration_transparent_material_scene`
|
||
- `rendering_integration_cull_material_scene`
|
||
- `rendering_integration_depth_sort_scene`
|
||
- `rendering_integration_material_state_scene`
|
||
- `rendering_integration_offscreen_scene`
|
||
|
||
`rendering_phase_regression` 当前是 Windows 下的 PowerShell 回归入口，依赖：
|
||
|
||
- `rendering_all_tests`
|
||
- `editor_tests`
|
||
- `XCEditor`
|
||
|
||
并执行：
|
||
|
||
- `scripts/Run-RendererPhaseRegression.ps1`
|
||
|
||
### 4.5 RHI
|
||
|
||
| 类别 | 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` |
|
||
|
||
抽象层单项 target：
|
||
|
||
- `rhi_unit_tests`
|
||
- `rhi_integration_minimal`
|
||
- `rhi_integration_triangle`
|
||
- `rhi_integration_quad`
|
||
- `rhi_integration_sphere`
|
||
- `rhi_integration_backpack`
|
||
|
||
后端单元测试 target：
|
||
|
||
- `rhi_d3d12_tests`
|
||
- `rhi_opengl_tests`
|
||
- `rhi_vulkan_tests`
|
||
|
||
后端集成测试 target：
|
||
|
||
- `d3d12_minimal_test`
|
||
- `d3d12_triangle_test`
|
||
- `d3d12_quad_test`
|
||
- `d3d12_sphere_test`
|
||
- `opengl_minimal_test`
|
||
- `opengl_triangle_test`
|
||
- `opengl_quad_test`
|
||
- `opengl_sphere_test`
|
||
- `vulkan_minimal_test`
|
||
- `vulkan_triangle_test`
|
||
- `vulkan_quad_test`
|
||
- `vulkan_sphere_test`
|
||
|
||
## 5. RHI 测试分层
|
||
|
||
RHI 当前分为五块：
|
||
|
||
- `tests/RHI/unit/`
|
||
- `tests/RHI/integration/`
|
||
- `tests/RHI/D3D12/`
|
||
- `tests/RHI/OpenGL/`
|
||
- `tests/RHI/Vulkan/`
|
||
|
||
边界规则：
|
||
|
||
- `tests/RHI/unit/` 与 `tests/RHI/integration/` 只能依赖公共 RHI 抽象接口。
|
||
- 后端私有头文件、原生句柄、后端专用 helper，只允许出现在对应后端目录。
|
||
- 如果抽象层测试为了通过而被迫引入后端 API，优先修 RHI，而不是给测试开后门。
|
||
- Vulkan 专属断言、原生句柄检查与直接依赖 Vulkan API 的测试，应继续收敛在 `tests/RHI/Vulkan/` 子树。
|
||
|
||
## 6. RHI 抽象层集成测试规范
|
||
|
||
### 6.1 当前目录
|
||
|
||
```text
|
||
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` 绑定路径的覆盖。
|
||
8. `backpack` 作为最接近真实资源路径的抽象层场景，不应随意削弱。
|
||
|
||
### 6.4 推荐验证方式
|
||
|
||
```bash
|
||
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. 推荐的验证策略
|
||
|
||
按改动类型选择最小有效验证：
|
||
|
||
- 改 `engine/RHI`：先跑 `rhi_abstraction_tests` 或 `rhi_backend_tests`
|
||
- 改 `engine/Rendering`：先跑 `rendering_unit_tests` 和最相关的 `rendering_integration_*`
|
||
- 改 `editor/Viewport`：先跑 `editor_tests`，必要时再跑 `rendering_phase_regression`
|
||
- 改脚本运行时 / managed / 项目脚本程序集：先跑 `scripting_tests`；如果还要验证 editor / runtime 实际使用的项目程序集目录，再补构建 `xcengine_project_managed_assemblies`
|
||
- 改资源导入 / `.meta` / artifact：优先跑对应 `Resources/*` tests
|
||
|
||
在这些最小验证通过后，再决定是否扩展到：
|
||
|
||
```bash
|
||
ctest --test-dir build -C Debug --output-on-failure
|
||
```
|
||
|
||
## 8. 文档维护要求
|
||
|
||
以下变化必须同步更新本文档：
|
||
|
||
- 测试目录结构变化
|
||
- 新增或删除测试 target
|
||
- rendering integration 场景变化
|
||
- RHI 抽象层 GT 图规则变化
|
||
- PowerShell 回归入口变化
|
||
- 项目脚本程序集参与测试的方式变化
|
||
|
||
禁止继续保留和当前仓库状态不一致的旧说明。
|