xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6159eef3af782f45b8b1fe13336e73608366ee9d
XCEngine/tests/TEST_SPEC.md

10 KiB
Raw Blame History

XCEngine 测试规范

最后更新：2026-04-04

1. 目标

本文档描述当前仓库里已经落地、已经生效、并且应当长期维护的测试基线。

重点覆盖：

  • tests/ 的真实目录结构
  • 当前 CMake / CTest 入口
  • RHI 测试分层边界
  • Rendering / Editor / Scripting 相关聚合 target

如果目录结构、target 名称、场景覆盖范围或回归入口变化，必须同步更新本文档。

2. 顶层结构

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

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 配置

cmake -S . -B build -A x64

如果当前任务不需要 Mono：

cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF

以下情况需要重新配置：

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

3.2 通用入口

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

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 推荐验证方式

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

在这些最小验证通过后，再决定是否扩展到：

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

8. 文档维护要求

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

  • 测试目录结构变化
  • 新增或删除测试 target
  • rendering integration 场景变化
  • RHI 抽象层 GT 图规则变化
  • PowerShell 回归入口变化
  • 项目脚本程序集参与测试的方式变化

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

Reference in New Issue View Git Blame Copy Permalink