Falcor项目单元测试系统详解

Falcor项目单元测试系统详解

Falcor Real-Time Rendering Framework 项目地址: https://gitcode.com/gh_mirrors/fal/Falcor

概述

Falcor作为一款实时渲染框架，其单元测试系统采用了自定义的实现方案，专门针对图形计算领域的特点进行了优化。这套系统不仅能测试常规的CPU逻辑，还能直接对GPU计算进行验证，确保渲染管线各环节的正确性。

测试系统架构

Falcor的单元测试系统核心位于Tools/FalcorTest项目中，主要包含以下关键组件：

1. 测试运行器：负责加载和执行所有注册的测试用例
2. 测试上下文：特别是GPUUnitTestContext类，为GPU测试提供执行环境
3. 断言系统：提供丰富的断言宏用于结果验证
4. 报告系统：生成格式化的测试结果输出

运行单元测试

通过脚本运行

推荐使用tests/run_unit_tests.bat批处理文件执行测试，它提供了丰富的配置选项：

./run_unit_tests.bat --config windows-ninja-msvc-Release --category gpu

主要参数说明：

• --environment：指定运行环境配置文件
• --config：选择构建配置（如Debug/Release）
• --category：筛选测试类型（cpu/gpu/all）

直接运行可执行文件

也可以直接运行构建生成的FalcorTest.exe，支持以下常用选项：

FalcorTest.exe --category=gpu --device-type=d3d12 --filter="RadicalInverse"

关键参数：

• --device-type：指定图形API（d3d12/vulkan）
• --filter：通过正则表达式筛选测试用例
• --repeat：重复执行测试次数
• --xml-report：生成XML格式测试报告

编写测试用例

CPU测试编写规范

CPU测试使用CPU_TEST宏定义，示例：

CPU_TEST(VectorNormalization)
{
    float3 v(1.f, 2.f, 3.f);
    float len = length(v);
    float3 normalized = normalize(v);
    
    EXPECT_NEAR(1.0f, length(normalized), 1e-6f);
    EXPECT_EQ(v/len, normalized);
}

常用断言宏：

• EXPECT_EQ/EXPECT_NE：等于/不等于
• EXPECT_{GT,GE,LT,LE}：大小比较
• EXPECT_NEAR：浮点数近似相等
• EXPECT：通用布尔条件

GPU测试编写规范

GPU测试需要配合计算着色器，典型结构：

1. 编写计算着色器（如MatrixMul.cs.slang）：

RWStructuredBuffer<float> output;
cbuffer Inputs { 
    float4x4 matA; 
    float4x4 matB;
};

[numthreads(1, 1, 1)]
void main()
{
    output[0] = mul(matA, matB);
}

2. 编写测试代码：

GPU_TEST(MatrixMultiplication)
{
    ctx.createProgram("MatrixMul.slang.hlsl");
    ctx.allocateStructuredBuffer("output", 16);
    
    float4x4 matA = /* 初始化矩阵 */;
    float4x4 matB = /* 初始化矩阵 */;
    
    ctx["Inputs"]["matA"] = matA;
    ctx["Inputs"]["matB"] = matB;
    ctx.runProgram();

    const float4x4* result = ctx.mapBuffer<const float4x4>("output");
    EXPECT_EQ(matA * matB, *result);  // 验证矩阵乘法结果
    ctx.unmapBuffer("output");
}

GPUUnitTestContext关键方法：

• createProgram：加载计算着色器
• allocateStructuredBuffer：创建GPU缓冲区
• mapBuffer/unmapBuffer：数据读写
• runProgram：执行计算着色器

测试输出与调试

测试失败时会输出详细信息，包括：

• 失败断言的具体位置
• 期望值与实际值对比
• 自定义调试信息（通过<<操作符添加）

示例调试输出：

Test failed: result[0] == expected (0.5 vs. 0.6) 
Test case: CosineSimilarity
Shader: Cosine.cs.slang
Thread: 0

测试管理技巧

1. 临时跳过测试：

GPU_TEST(BrokenFeature, "暂时跳过，等待修复BUG-1234")
{
    // 测试代码
}

2. 测试分类：

• 使用CPU_TEST/GPU_TEST宏自动分类
• 运行时可通过--category参数筛选

3. 性能测试： 测试输出中包含执行时间，可用于简单性能监控：

shadingutilstests.cpp/RadicalInverse (GPU) : PASSED (65 ms)

最佳实践

1. 测试独立性：每个测试应完全独立，不依赖其他测试状态
2. 资源清理：确保测试后释放所有GPU资源
3. 随机测试：对于随机算法，应设置固定随机种子确保可重复性
4. 边界测试：特别关注边界条件的测试
5. GPU兼容性：考虑不同GPU架构的差异

通过这套测试系统，Falcor项目能够有效保证核心渲染功能的正确性，特别是在跨平台和跨GPU架构的场景下，为图形算法的开发提供了可靠的验证机制。

Falcor Real-Time Rendering Framework 项目地址: https://gitcode.com/gh_mirrors/fal/Falcor