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 建议测试用例

```cpp
// 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 建议结构

```bash
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 开始