XCEngine/docs/plan/OpenGL测试实施计划.md

OpenGL 测试实施计划

1. 概述

本文档是 docs/OpenGL后端测试设计.md 的实施细化计划，基于设计文档中的 5 阶段实现优先级，结合 D3D12 测试经验（54 个测试）制定。

1.1 目标

• 搭建完整的 OpenGL 后端测试框架
• 实现与 D3D12 对齐的 54+ 个测试用例
• 确保 CI 环境可用
• 支持无头渲染（headless）测试

1.2 测试组件总览

#	组件	测试数量	文件	优先级
1	OpenGLDevice	6	test_device.cpp	Phase 1
2	OpenGLBuffer	6	test_buffer.cpp	Phase 1
3	OpenGLFence	5	test_fence.cpp	Phase 1
4	OpenGLTexture	5	test_texture.cpp	Phase 2
5	OpenGLSampler	4	test_sampler.cpp	Phase 2
6	OpenGLShader	4	test_shader.cpp	Phase 3
7	OpenGLPipelineState	3	test_pipeline_state.cpp	Phase 3
8	OpenGLVertexArray	4	test_vertex_array.cpp	Phase 3
9	OpenGLCommandList	8	test_command_list.cpp	Phase 4
10	OpenGLRenderTargetView	4	test_render_target_view.cpp	Phase 4
11	OpenGLDepthStencilView	4	test_depth_stencil_view.cpp	Phase 4
12	OpenGLSwapChain	3	test_swap_chain.cpp	Phase 5
总计		56

---

2. 实施阶段

Phase 1: 核心基础设施（约 1 天）

2.1 创建目录结构

tests/RHI/OpenGL/
├── CMakeLists.txt
├── fixtures/
│   ├── OpenGLTestFixture.h
│   └── OpenGLTestFixture.cpp
└── Res/
    ├── Shader/
    ├── Texture/
    └── Data/

2.2 实现测试夹具

OpenGLTestFixture 是所有测试的基础：

功能	描述
SetUpTestSuite()	创建隐藏 GLFW 窗口和 GL 上下文
TearDownTestSuite()	销毁窗口，终止 GLFW
SetUp()	确保上下文激活，清除 GL 错误
TearDown()	重置 GL 状态，检查泄漏
CheckGLError()	检查并报告 GL 错误

GL 错误检查宏：

#define GL_CLEAR_ERRORS() do { while (glGetError() != GL_NO_ERROR); } while(0)
#define GL_CHECK(call) do { call; ASSERT_TRUE(CheckGLError(__FILE__, __LINE__)); } while(0)
#define GL_EXPECT_SUCCESS(call) do { call; EXPECT_EQ(glGetError(), GL_NO_ERROR); } while(0)

2.3 OpenGLDevice 测试（6 个）

测试用例	验证内容
CreateRenderWindow_ValidParams	窗口创建成功
CreateRenderWindow_DebugMode	调试模式创建
InitializeWithExistingWindow	现有窗口初始化
GetDeviceInfo_ReturnsValid	供应商/渲染器/版本信息
SwapBuffers_NoErrors	交换缓冲区无错误
PollEvents_ReturnsTrue	事件轮询正常

2.4 OpenGLBuffer 测试（6 个）

测试用例	验证内容
Initialize_VertexBuffer	顶点缓冲创建
Initialize_IndexBuffer	索引缓冲创建
Initialize_UniformBuffer	Uniform 缓冲创建
Initialize_Dynamic	动态缓冲创建
Bind_Unbind	缓冲绑定/解绑
Map_Unmap	数据映射操作

2.5 OpenGLFence 测试（5 个）

测试用例	验证内容
Initialize_Unsignaled	未 signaled 状态创建
Initialize_Signaled	signaled 状态创建
Signal_SetsValue	Signal 设置值
Wait_Blocks	Wait 阻塞等待
IsSignaled_ReturnsState	signaled 状态查询

2.6 验证步骤

# 构建
cmake --build build --config Debug

# 运行测试
./build/tests/RHI/OpenGL/Debug/opengl_tests.exe --gtest_filter=OpenGLTestFixture.Device*:OpenGLTestFixture.Buffer*:OpenGLTestFixture.Fence*

# 预期结果
[==========] 17 tests from OpenGLTestFixture
[  PASSED  ] 17 tests

---

Phase 2: 资源管理（约 1 天）

2.7 OpenGLTexture 测试（5 个）

测试用例	验证内容
Initialize_2DTexture	2D 纹理创建
Initialize_CubeMap	立方体纹理创建
Bind_Unbind	纹理绑定/解绑
GenerateMipmap	Mipmap 生成
SetFiltering_SetWrapping	过滤/环绕参数

2.8 OpenGLSampler 测试（4 个）

测试用例	验证内容
Initialize_Default	默认采样器创建
Initialize_Custom	自定义采样器创建
Bind_Unbind	采样器绑定/解绑
GetID_ReturnsValid	采样器 ID 有效

2.9 验证步骤

# 运行资源管理测试
./build/tests/RHI/OpenGL/Debug/opengl_tests.exe --gtest_filter=OpenGLTestFixture.Texture*:OpenGLTestFixture.Sampler*

# 预期结果
[==========] 9 tests from OpenGLTestFixture
[  PASSED  ] 9 tests

---

Phase 3: 渲染管线（约 1.5 天）

2.10 OpenGLShader 测试（4 个）

测试用例	验证内容
Compile_VertexFragment	顶点和片段着色器编译
Compile_WithGeometry	几何着色器编译
Compile_InvalidSource	无效源码编译失败
SetUniforms	Uniform 设置 (int/float/vec3/mat4)

2.11 OpenGLPipelineState 测试（3 个）

测试用例	验证内容
SetDepthStencilState	深度/模板状态设置
SetBlendState	混合状态设置
SetViewport_SetScissor	视口/裁剪矩形

2.12 OpenGLVertexArray 测试（4 个）

测试用例	验证内容
Initialize_CreatesVAO	VAO 创建
AddVertexBuffer	顶点缓冲添加
SetIndexBuffer	索引缓冲设置
Bind_Unbind	VAO 绑定/解绑

2.13 验证步骤

# 运行渲染管线测试
./build/tests/RHI/OpenGL/Debug/opengl_tests.exe --gtest_filter=OpenGLTestFixture.Shader*:OpenGLTestFixture.PipelineState*:OpenGLTestFixture.VertexArray*

# 预期结果
[==========] 11 tests from OpenGLTestFixture
[  PASSED  ] 11 tests

---

Phase 4: 命令与视图（约 1.5 天）

2.14 OpenGLCommandList 测试（8 个）

测试用例	验证内容
Clear_ColorBuffer	清除颜色缓冲
Clear_DepthStencil	清除深度/模板
SetVertexBuffer	设置顶点缓冲
SetIndexBuffer	设置索引缓冲
Draw_Triangles	绘制三角形
DrawIndexed_Indices	索引绘制
DrawInstanced	实例化绘制
Dispatch_ComputeShader	计算着色器分发

2.15 OpenGLRenderTargetView 测试（4 个）

测试用例	验证内容
Initialize_Texture2D	2D 纹理 RTV 创建
Initialize_Default	默认帧缓冲 RTV
Bind_Unbind	RTV 绑定/解绑
Clear_Color	清除颜色

2.16 OpenGLDepthStencilView 测试（4 个）

测试用例	验证内容
Initialize_Texture2D	2D 纹理 DSV 创建
Initialize_DepthOnly	仅深度 DSV
Bind_Unbind	DSV 绑定/解绑
ClearDepthStencil	清除深度/模板

2.17 验证步骤

# 运行命令与视图测试
./build/tests/RHI/OpenGL/Debug/opengl_tests.exe --gtest_filter=OpenGLTestFixture.CommandList*:OpenGLTestFixture.RenderTargetView*:OpenGLTestFixture.DepthStencilView*

# 预期结果
[==========] 16 tests from OpenGLTestFixture
[  PASSED  ] 16 tests

---

Phase 5: 窗口管理（约 0.5 天）

2.18 OpenGLSwapChain 测试（3 个）

测试用例	验证内容
Initialize_Window	交换链初始化
Present_VSync	垂直同步显示
Resize_ChangesSize	调整大小

2.19 验证步骤

# 运行窗口管理测试
./build/tests/RHI/OpenGL/Debug/opengl_tests.exe --gtest_filter=OpenGLTestFixture.SwapChain*

# 预期结果
[==========] 3 tests from OpenGLTestFixture
[  PASSED  ] 3 tests

---

3. 完整验证

3.1 运行所有测试

# 完整测试
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure

# 预期结果
[==========] 56 tests from 1 test suite.
[  PASSED  ] 56 tests

3.2 测试分类统计

分类	数量	占比
初始化测试	18	32%
绑定/解绑测试	10	18%
数据操作测试	8	14%
状态设置测试	10	18%
绘制/执行测试	10	18%

---

4. CI 配置

4.1 GitHub Actions

# .github/workflows/opengl-tests.yml
name: OpenGL Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Configure
        run: cmake -B build -S . -G "Visual Studio 17 2022"
      
      - name: Build
        run: cmake --build build --config Debug
      
      - name: Run Tests
        run: ctest --test-dir build -C Debug --output-on-failure

4.2 Linux CI（可选）

Linux 下需要配置 Mesa 软件渲染：

- name: Run Tests
  env:
    MESA_GL_VERSION_OVERRIDE: 4.6
    MESA_GALLIUM_DRIVER: llvmpipe
  run: ctest --test-dir build -C Debug --output-on-failure

---

5. 任务清单

阶段 1：基础设施

• 1.1 创建 tests/RHI/OpenGL/CMakeLists.txt
• 1.2 创建 tests/RHI/OpenGL/fixtures/OpenGLTestFixture.h
• 1.3 创建 tests/RHI/OpenGL/fixtures/OpenGLTestFixture.cpp
• 1.4 实现 test_device.cpp（6 个测试）
• 1.5 实现 test_buffer.cpp（6 个测试）
• 1.6 实现 test_fence.cpp（5 个测试）
• 1.7 构建验证（17 个测试）

阶段 2：资源管理

• 2.1 实现 test_texture.cpp（5 个测试）
• 2.2 实现 test_sampler.cpp（4 个测试）
• 2.3 构建验证（9 个测试）

阶段 3：渲染管线

• 3.1 实现 test_shader.cpp（4 个测试）
• 3.2 实现 test_pipeline_state.cpp（3 个测试）
• 3.3 实现 test_vertex_array.cpp（4 个测试）
• 3.4 构建验证（11 个测试）

阶段 4：命令与视图

• 4.1 实现 test_command_list.cpp（8 个测试）
• 4.2 实现 test_render_target_view.cpp（4 个测试）
• 4.3 实现 test_depth_stencil_view.cpp（4 个测试）
• 4.4 构建验证（16 个测试）

阶段 5：窗口管理

• 5.1 实现 test_swap_chain.cpp（3 个测试）
• 5.2 完整测试验证（56 个测试）
• 5.3 提交并推送

---

6. 关键注意事项

6.1 窗口依赖

• OpenGL 必须有 GLFW 窗口上下文
• 使用 GLFW_VISIBLE = GLFW_FALSE 创建隐藏窗口
• 每个测试前 glfwMakeContextCurrent()

6.2 GL 状态污染

• OpenGL 状态是全局的，必须隔离
• TearDown() 中重置所有 GL 状态
• 测试结束后 glBindBuffer(..., 0) 等

6.3 错误检查

• 使用 GL_CHECK() 宏验证每个 GL 调用
• 测试开始时 GL_CLEAR_ERRORS()
• 捕获 GL 错误并转换为测试失败

6.4 与 D3D12 对齐

• 保持相同的测试数量级（54+）
• 使用相同的 TEST_F 宏
• 遵循相同的命名约定

---

7. 后续工作

• 资源泄漏检测工具
• 性能基准测试
• 截图对比测试
• Linux CI 配置
• macOS 支持

---

文档版本：1.0
创建日期：2026年3月17日
基于文档：docs/OpenGL后端测试设计.md、tests/RHI/D3D12/