XCEngine/tests/RHI/D3D12/TEST_SPEC.md

# D3D12 测试专项规范

## 1. 构建命令

```bash
# 构建所有
cmake --build <build> --config Debug

# 只构建单元测试
cmake --build <build> --target d3d12_engine_tests --config Debug

# 只构建集成测试
cmake --build <build> --target D3D12_Sphere D3D12_Triangle D3D12_Quad D3D12_Minimal --config Debug
```

## 2. 运行测试

```bash
# 运行所有已注册的测试（单元 + 集成）
cd <build>
ctest -C Debug --output-on-failure

# 只运行单元测试
cd <build>/tests/RHI/D3D12/unit
ctest -C Debug --output-on-failure

# 只运行集成测试
cd <build>/tests/RHI/D3D12/integration
ctest -C Debug --output-on-failure
```

## 3. 集成测试列表

| 测试名 | Target | Golden Image |
|--------|--------|-------------|
| D3D12_Minimal_Integration | D3D12_Minimal | `minimal/GT.ppm` |
| D3D12_Quad_Integration | D3D12_Quad | `quad/GT.ppm` |
| D3D12_Sphere_Integration | D3D12_Sphere | `sphere/GT.ppm` |
| D3D12_Triangle_Integration | D3D12_Triangle | `triangle/GT.ppm` |

## 4. CTest 注册机制

集成测试通过 `add_test()` 注册到 CTest：

```cmake
add_test(NAME D3D12_Sphere_Integration
    COMMAND ${Python3_EXECUTABLE} $<TARGET_FILE_DIR:D3D12_Sphere>/run_integration_test.py
        $<TARGET_FILE:D3D12_Sphere>
        sphere.ppm
        ${CMAKE_CURRENT_SOURCE_DIR}/GT.ppm
        0
    WORKING_DIRECTORY $<TARGET_FILE_DIR:D3D12_Sphere>
)
```

`run_integration_test.py` 负责：
1. 启动 exe
2. 等待完成
3. 调用 `compare_ppm.py` 比对图像
4. 返回 0（通过）/ 1（失败）

## 5. CI 配置

```yaml
name: D3D12 Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Configure CMake
        run: cmake -B build -DCMAKE_BUILD_TYPE=Debug
      
      - name: Build D3D12
        run: cmake --build build --config Debug
      
      - name: Run Tests
        run: cd build && ctest -C Debug --output-on-failure
```

## 6. 目录结构

```
tests/RHI/D3D12/
├── unit/
│   ├── CMakeLists.txt
│   ├── fixtures/
│   │   ├── D3D12TestFixture.h
│   │   └── D3D12TestFixture.cpp
│   ├── test_*.cpp
│   └── ...
└── integration/
    ├── CMakeLists.txt
    ├── run_integration_test.py    # 测试 wrapper
    ├── compare_ppm.py            # 图像比对
    ├── minimal/                  # 最小测试
    │   ├── main.cpp
    │   └── GT.ppm
    ├── quad/
    │   ├── main.cpp
    │   └── GT.ppm
    ├── sphere/
    │   ├── main.cpp
    │   ├── GT.ppm
    │   └── Res/
    │       ├── Image/
    │       └── Shader/
    └── triangle/
        ├── main.cpp
        └── GT.ppm
```

---

**最后更新**: 2026-03-22