XCEngine/tests/RHI/Vulkan/TEST_SPEC.md

# Vulkan 测试专项规范

本文档是 [tests/TEST_SPEC.md](../TEST_SPEC.md) 在 Vulkan 后端上的补充入口，描述当前已经落地的 Vulkan 专项测试树。

## 1. 当前结构

```text
tests/RHI/Vulkan/
|- CMakeLists.txt
|- TEST_SPEC.md
\- integration/
|  |- CMakeLists.txt
|  |- quad/
|  |  |- CMakeLists.txt
|  |  |- GT.ppm
|  |  |- main.cpp
|  |  \- Res/
|  |- sphere/
|  |  |- CMakeLists.txt
|  |  |- GT.ppm
|  |  |- main.cpp
|  |  \- Res/
|  \- minimal/
|     |- CMakeLists.txt
|     |- GT.ppm
|     \- main.cpp
\- unit/
   |- CMakeLists.txt
   |- fixtures/
   |  |- VulkanTestFixture.cpp
   |  \- VulkanTestFixture.h
   |- test_compute.cpp
   |- test_descriptor_set.cpp
   |- test_pipeline_layout.cpp
   |- test_pipeline_state.cpp
   |- test_render_pass.cpp
   \- test_shader.cpp
```

## 2. 当前目标

| 类别 | target |
| --- | --- |
| Vulkan 后端单元测试 | `rhi_vulkan_tests` |
| Vulkan 后端集成测试 | `vulkan_minimal_test` `vulkan_triangle_test` `vulkan_quad_test` `vulkan_sphere_test` |
| Vulkan 后端聚合 target | `rhi_vulkan_backend_tests` |

## 3. 当前覆盖

`rhi_vulkan_tests` 当前覆盖 Vulkan 后端专属语义，包括：

- RenderPass / Framebuffer clear 到真实 Vulkan 纹理后的像素结果验证
- `CopyResource` 纹理复制后的像素回读验证
- SPIR-V / GLSL 两条 shader 创建路径
- 基于 GLSL 的 graphics pipeline 创建
- UAV 视图创建与 compute dispatch 写纹理链路
- RTV / DSV / SRV 视图创建与原生 image-view 句柄有效性
- `Sampler` 创建与原生 sampler 句柄有效性
- `DescriptorSet` 的原生句柄、绑定布局元数据与常量缓冲脏标记行为
- graphics draw 到离屏纹理后的像素回读，以及 `SetGraphicsDescriptorSets(firstSet != 0)` 绑定路径
- `PipelineLayout` 的显式 set-layout 聚合与 flat-count 合成逻辑

当前这些 Vulkan backend unit 用例已经按职责拆分为 fixture / render-pass / shader / pipeline / compute 几个文件，避免后续继续堆到单个巨型测试文件中。

这些测试允许直接依赖 Vulkan 具体类型、原生句柄和 Vulkan API；这类断言不应再回流到 `tests/RHI/unit/`。

## 4. 分层约束

- `tests/RHI/unit/` 继续只承载 RHI 抽象层统一语义测试。
- `tests/RHI/Vulkan/unit/` 承载 Vulkan 专属断言、原生对象检查和需要直接调用 Vulkan API 的测试。
- `tests/RHI/Vulkan/integration/` 承载 Vulkan 后端直连场景，当前已经落地 `minimal / triangle / quad / sphere`。

## 5. 推荐执行方式

```bash
cmake --build build --config Debug --target rhi_vulkan_backend_tests
build\tests\RHI\Vulkan\unit\Debug\rhi_vulkan_tests.exe --gtest_brief=1

cmake --build build --config Debug --target vulkan_sphere_test
ctest -C Debug -R "vulkan_(minimal|triangle|quad|sphere)_test" --test-dir build
```