XCEngine/tests/RHI/D3D12/TEST_IMPROVEMENT_PLAN.md

D3D12 测试改进计划

一、当前状态

1.1 已完成

阶段	内容	状态
Phase 0	单元测试框架搭建 (54 tests)	✅ 完成
Phase 1	集成测试注册到 CTest	✅ 完成

1.2 测试统计

单元测试: 54 tests (全部通过)
集成测试: 2 tests (D3D12_Minimal_Integration ✅, D3D12_RenderModel_Integration 待修复)

1.3 目录结构

tests/RHI/D3D12/
├── unit/
│   ├── CMakeLists.txt
│   ├── fixtures/D3D12TestFixture.h
│   └── test_*.cpp           # 54 tests
└── integration/
    ├── CMakeLists.txt        # 已注册 CTest
    ├── main_minimal.cpp      # D3D12_Minimal_Integration
    ├── main_render.cpp       # D3D12_RenderModel_Integration (有API问题)
    ├── run_integration_test.py
    ├── compare_ppm.py
    ├── GT.ppm               # RenderModel 用
    └── GT_minimal.ppm       # Minimal 用

---

二、Phase 2: 测试命名规范化

2.1 目标

将测试命名统一为 Component_Category_SubBehavior 格式。

2.2 当前命名问题

当前名称	问题
D3D12TestFixture.Buffer_Placeholder	"Placeholder" 无意义
D3D12TestFixture.Buffer_CreateDefaultHeap	格式不统一
D3D12TestFixture.CommandQueue_ExecuteCommandList	未用下划线分隔

2.3 目标格式

Component_Category_SubBehavior

部分	说明	示例
Component	被测组件	Device, Buffer, Texture, CommandQueue
Category	操作类别	Create, Get, Set, Map, Reset
SubBehavior	具体行为	DefaultHeap, UploadHeap, GPUAddress

2.4 重命名规则

规则 1: 组件名称标准化

当前	规范
D3D12TestFixture	Device, Buffer, Texture... (直接用组件名)

规则 2: 操作类别标准化

Category	说明	示例
Create	创建资源	Buffer_Create, Texture_Create
Get	获取属性	Device_GetAdapterInfo
Set	设置属性	Buffer_SetName
Map	内存映射	Buffer_MapUnmap
Reset	重置状态	CommandAllocator_Reset

规则 3: Placeholder 测试

所有 *_Placeholder 测试应：

• 删除（如果只验证对象存在）
• 或改为有意义的验证测试

2.5 具体重命名方案

Buffer tests (6 → 5, 删除 Placeholder)

当前名称	建议名称
Buffer_Placeholder	(删除)
Buffer_CreateDefaultHeap	Buffer_Create_DefaultHeap
Buffer_CreateUploadHeap	Buffer_Create_UploadHeap
Buffer_GetGPUAddress	Buffer_Get_GPUAddress
Buffer_MapUnmap	Buffer_Map_Unmap
Buffer_AlignmentRequirements	Buffer_Get_AlignmentRequirements

Texture tests (5 → 5)

当前名称	建议名称
Texture_Placeholder	(删除或改为 Texture_Create_2D)
Texture_Create2D	Texture_Create_2D
Texture_Create3D	Texture_Create_3D
Texture_CreateMultipleMips	Texture_Create_MultipleMips
Texture_CreateTextureArray	Texture_Create_Array

CommandAllocator tests (4 → 3)

当前名称	建议名称
CommandAllocator_Placeholder	(删除)
CommandAllocator_Reset	CommandAllocator_Reset_Basic
CommandAllocator_ResetMultiple	CommandAllocator_Reset_Multiple
CommandAllocator_DifferentTypes	CommandAllocator_Create_DifferentTypes

其他组件类似处理...

2.6 实施步骤

1. 批量重命名测试用例 (test_*.cpp)
2. 更新 fixtures/D3D12TestFixture.h (如有必要)
3. 运行测试验证
4. 更新文档

2.7 CMake 配置

无需修改，测试名称不影响构建。

---

三、Phase 3: 错误路径测试

3.1 目标

添加负面测试，验证错误处理。

3.2 建议测试用例

// Device 错误测试
Device_Create_NullAdapter      // 无效适配器
Device_Create_InvalidFeatureLevel // 不支持的功能级别

// Buffer 错误测试
Buffer_Create_ZeroSize         // 零大小
Buffer_Create_OverflowSize     // 超出限制大小

// Texture 错误测试
Texture_Create_ZeroDimension   // 零尺寸
Texture_Create_InvalidFormat   // 无效格式

// CommandList 错误测试
CommandList_Close_WithoutRecord // 未录制就关闭
CommandList_Reset_WhileRecording // 录制中重置

---

四、Phase 4: Golden Image 扩展

4.1 目标

为更多集成测试场景添加 Golden Template。

4.2 建议添加

场景	Golden Template	阈值
2D 渲染测试	GT_render_2d.ppm	5%
深度测试	GT_depth_test.ppm	5%
混合模式测试	GT_blend.ppm	5%

---

五、Phase 5: CI 集成

5.1 目标

创建跨平台测试运行脚本。

5.2 建议结构

scripts/
└── run_tests.py              # 统一测试入口

5.3 功能需求

• 自动检测平台 (Windows/Linux)
• 运行单元测试
• 运行集成测试 (可选，需 GUI)
• 生成测试报告
• 支持 CI 环境

---

六、优先级和排期

Phase	优先级	估计工作量	说明
Phase 2	P1	中	纯重命名，无代码逻辑变更
Phase 3	P1	高	需设计错误注入方案
Phase 4	P2	中	需手动生成 Golden Images
Phase 5	P2	低	主要是脚本工作

---

七、待解决问题

1. D3D12_RenderModel_Integration - main_render.cpp API 不兼容，需修复
2. GUI 集成测试 - CTest 无法直接运行 Win32 GUI 程序 (已用 Python wrapper 解决)
3. Golden Image 更新流程 - 如何在硬件差异时更新 GT

---

文档版本: 1.0 更新日期: 2026-03-20 当前阶段: Phase 1 完成，等待 Phase 2 开始