《OGRE 3D 渲染引擎原理与架构》14.1 测试体系

OGRE 测试体系按层划分:Tests/OgreMain 用 gtest 做单元测试、VisualTests 做渲染一致性、fuzz 做模糊回归;Tests/CMakeLists.txt 用 OGRE_BUILD_TESTS 门控并自动下载 googletest 1.16.0。lab 复现迷你 gtest 的注册、执行、容差断言与跳过。

14.1 测试体系

规模化不只意味着「更多对象」,还意味着「更难改」——改动引擎核心(数学库、序列化、渲染状态)时,必须有东西兜底。OGRE 在 Tests/ 下建立了三层测试体系:单元测试(OgreMain/,gtest 驱动,验证数学与数据结构)、渲染一致性测试(VisualTests/,开窗口跑真实场景并截图对比)、模糊测试(fuzz/,用 libFuzzer 喂随机输入找崩溃)。这一节先看整体布局与单元测试这一层。

本章与站内既有内容的分工

《游戏引擎实现原理》(helio 四卷)用自研 lab 与闸门做可运行性验证;这里解析真实 OGRE 的测试基建:CMake 怎么门控与拉取 gtest、测试文件怎么写(TEST 宏、EXPECT_NEAR 容差断言、GTEST_SKIP 条件跳过),以及单元测试目录为什么长这样。

测试目录分层

Tests/ 的顶层布局本身就是一张分层图:

目录职责驱动
Tests/OgreMain/核心数学/数据结构单元测试(QuaternionTests、VectorTests、BitwiseTests、MeshSerializerTests 等 20+ 文件)googletest
Tests/VisualTests/真实渲染场景:开窗口、摆对象、按帧截图自研 VisualTest 框架(14.2 细讲)
Tests/fuzz/对图像、脚本、压缩流喂随机输入的健壮性测试libFuzzer
Tests/src/main.cpp单元测试程序的入口gtest 的 RUN_ALL_TESTS

单元测试文件按「被测模块」命名——PixelFormatTests.cpp 测 PixelFormat、QuaternionTests.cpp 测 Quaternion、FileSystemArchiveTests.cpp 测存档层。每个 .cpp 配一个同名 .h,头文件放 fixture(测试固件)与共享声明。

CMake 门控与 gtest 集成

Tests/CMakeLists.txt 把整个测试构建包在 OGRE_BUILD_TESTS 开关里,需要时自动下载 googletest:

// Tests/CMakeLists.txt:OGRE_BUILD_TESTS 门控与 gtest 集成(v14.6.3 源码摘录,已删减)
    # Configure Tests build
    if (OGRE_BUILD_TESTS)
      # enable CTest
      ENABLE_TESTING()
      INCLUDE(CTest)

      if(NOT EXISTS ${PROJECT_BINARY_DIR}/googletest-1.16.0)
        message(STATUS "Building gtest")
        file(DOWNLOAD
            https://github.com/google/googletest/releases/download/v1.16.0/googletest-1.16.0.tar.gz
            ${PROJECT_BINARY_DIR}/release-1.16.0.tar.gz)
        execute_process(COMMAND ${CMAKE_COMMAND}
            -E tar xf release-1.16.0.tar.gz WORKING_DIRECTORY ${PROJECT_BINARY_DIR})
        execute_process(COMMAND ${BUILD_COMMAND_COMMON}
            ${PROJECT_BINARY_DIR}/googletest-1.16.0
            -Dgtest_force_shared_crt=TRUE
            -DBUILD_GMOCK=FALSE
            WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/googletest-1.16.0)
        ...
      endif()
      find_package(GTest REQUIRED CONFIG)
      include_directories(${CMAKE_CURRENT_SOURCE_DIR}/Common/include)

        # unit tests are go!
        include_directories(${CMAKE_CURRENT_SOURCE_DIR}/OgreMain/include)

        file(GLOB HEADER_FILES "${CMAKE_CURRENT_SOURCE_DIR}/OgreMain/include/*.h")
        file(GLOB SOURCE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/OgreMain/src/*.cpp"
          "${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp")

几个值得注意的工程决策:

  • ENABLE_TESTING() + INCLUDE(CTest):测试集成进 CTest,ctest 一条命令跑全部用例。
  • 版本锁定 googletest 1.16.0:file(DOWNLOAD) 固定发布版本,避免「昨天还能编、今天上游变了」的漂移。
  • -DBUILD_GMOCK=FALSE:只要 gtest 不要 gmock,少拉一个依赖。
  • file(GLOB SOURCE_FILES):新增一个 *Tests.cpp 自动被纳入构建,写测试不需要改 CMake——代价是新增文件要重跑 CMake 才能被 GLOB 捕获(GLOB 不会自动重扫描)。

一个真实的单元测试

QuaternionTests.cpp 是典型的 gtest 风格——TEST 宏定义用例,断言用 EXPECT_*(失败只记录不中断,同用例后续断言继续跑):

// Tests/OgreMain/src/QuaternionTests.cpp:TEST 用例与跳过(v14.6.3 源码摘录,已删减)
    TEST(QuaternionTests,Norm)
    {
        EXPECT_NEAR(Quaternion(0, 2, 2, 2).Norm(), Vector3(2, 2, 2).length(), 1e-6);
    }
    ...
    TEST(QuaternionTests, Precision)
    {
        if(OGRE_DOUBLE_PRECISION == 0)
            GTEST_SKIP() << "OGRE_DOUBLE_PRECISION required";

        Quaternion rot(Radian(5), Vector3::UNIT_X);
        Quaternion rot_inv(Radian(-5), Vector3::UNIT_X);
        Vector3 v_s(0, 5e6, 0);
        Vector3 v_e = rot * v_s;
        v_e = rot_inv * v_e;
        EXPECT_LE((v_s - v_e).length(), 0.6);
    }

两个用例展示了测试体系的两个关键工具:

  • EXPECT_NEAR(a, b, 1e-6):浮点结果用「容差」而非「相等」断言——Quaternion::Norm() 与 Vector3::length() 是两条不同的代码路径,浮点舍入不同,逐位相等断言会误报。
  • GTEST_SKIP():条件跳过。Precision 用例需要 OGRE_DOUBLE_PRECISION 编译开关(Quaternion 内部用 double),在默认单精度构建里直接跳过——跳过也是一种通过,它把「不适用」与「失败」区分开。

同一文件的 FromVectors 用例还演示了数据驱动:一个 Vector3 list[][2] 数组装 10 组「from/to 向量对」,循环里对每组断言 getRotationTo(to) * from 归一化后与 to 同向,且长度不变。一组测试代码 + 一张数据表 = 10 个测试实例,这是矩阵类测试的惯用手法。

源码定位

  • Tests/CMakeLists.txt :if (OGRE_BUILD_TESTS)(14)、ENABLE_TESTING()(16)、file(DOWNLOAD ... googletest-1.16.0.tar.gz ...)(22-25)、find_package(GTest REQUIRED CONFIG)(36)、file(GLOB SOURCE_FILES ...)(43-45)
  • Tests/OgreMain/src/QuaternionTests.cpp :TEST(QuaternionTests,Norm)(34-37)、TEST(QuaternionTests,FromVectors)(39-81)、TEST(QuaternionTests, Precision)(126-137)、GTEST_SKIP() << "OGRE_DOUBLE_PRECISION required"(129)
  • Tests/OgreMain/src/:20+ 个 *Tests.cpp 单元测试文件(VectorTests.cpp、PixelFormatTests.cpp、MeshSerializerTests.cpp 等)

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面用纯 C++ 复现 gtest 的核心骨架:注册、执行、容差断言、跳过、失败不中断。它与 src/ogre-ext-14-1-test-suite.cpp 逐字节一致:

// file: src/ogre-ext-14-1-test-suite.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-14-1-test-suite.cpp -o bin/ogre-ext-14-1-test-suite && ./bin/ogre-ext-14-1-test-suite
//
// 复现 OGRE 单元测试骨架(对应 Tests/OgreMain/src/QuaternionTests.cpp 与
// Tests/CMakeLists.txt):
//   REPRO_TEST 宏在静态初始化期把用例注册进 registry(对应 gtest 的 TEST 宏);
//   expectNear 对应 EXPECT_NEAR 容差断言,expectTrue 对应 EXPECT_TRUE;
//   kSkipped 状态对应 GTEST_SKIP 条件跳过;
//   单个用例失败不中断其余用例(失败计数累计)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cmath>
#include <cstdint>
#include <string>
#include <vector>

namespace ogre_repro {

enum class Status { kPending, kSkipped };

struct TestCase {
  const char* name;
  bool (*fn)();
  Status status;
};

std::vector<TestCase>& registry() {
  static std::vector<TestCase> r;
  return r;
}

// 对应 gtest 的失败统计(只记录,不中断当前用例)
int g_checks = 0;
int g_failures = 0;

// 对应 EXPECT_NEAR(a, b, tol)
bool expectNear(double a, double b, double tol) {
  ++g_checks;
  if (std::fabs(a - b) > tol) {
    ++g_failures;
    return false;
  }
  return true;
}

// 对应 EXPECT_TRUE(cond)
bool expectTrue(bool cond) {
  ++g_checks;
  if (!cond) ++g_failures;
  return cond;
}

// 对应 gtest 的 TEST(Suite, Name):注册用例并在执行期调用
#define REPRO_TEST(name)                                                  \
  static bool repro_test_##name();                                        \
  struct repro_reg_##name {                                               \
    repro_reg_##name() {                                                  \
      registry().push_back(TestCase{#name, repro_test_##name, Status::kPending}); \
    }                                                                     \
  } repro_inst_##name;                                                    \
  static bool repro_test_##name()

REPRO_TEST(Norm) {
  // 对应 QuaternionTests.Norm:向量部分长度 == Vector3::length
  double v[3] = {2, 2, 2};
  double norm = std::sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
  return expectNear(norm, 3.4641016151377544, 1e-6);  // sqrt(12)
}

REPRO_TEST(FromVectors_Identity) {
  // 对应 FromVectors 边角:同向向量不产生旋转
  double from[3] = {1, 0, 0}, to[3] = {1, 0, 0};
  double cosAng = from[0] * to[0];  // 单位长度向量的点积
  bool ok = expectNear(cosAng, 1.0, 1e-6);
  return ok && expectTrue(cosAng <= 1.0);
}

REPRO_TEST(FromVectors_NullFrom) {
  // 对应 FromVectors 零向量边角:无正确旋转,返回 IDENTITY
  double from[3] = {0, 0, 0};
  bool ok = expectTrue(from[0] == 0 && from[1] == 0 && from[2] == 0);
  return ok && expectTrue(true);
}

// 对应 GTEST_SKIP:Precision 用例在单精度构建下跳过
static bool skipped_registered = []() {
  registry().push_back(TestCase{"Precision", nullptr, Status::kSkipped});
  return true;
}();

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 注册发生在静态初始化期:3 个 pending + 1 个 skipped
  CHECK(registry().size() == 4);

  // 执行 pending 用例,跳过 kSkipped
  int skippedCount = 0;
  for (auto& tc : registry())
    if (tc.status == Status::kSkipped) ++skippedCount;
  CHECK_EQ(skippedCount, 1);

  bool allOk = true;
  for (auto& tc : registry()) {
    if (tc.status != Status::kSkipped) {
      if (!tc.fn()) allOk = false;
    }
  }
  CHECK(allOk);
  // Norm 1 个 + Identity 2 个 + NullFrom 2 个
  CHECK_EQ(g_checks, 5);
  CHECK_EQ(g_failures, 0);

  // 失败不中断:一个断言失败后,后续断言照常执行
  g_checks = 0;
  g_failures = 0;
  bool r1 = expectNear(1.0, 2.0, 0.1);
  bool r2 = expectTrue(true);
  CHECK(!r1);
  CHECK(r2);
  CHECK_EQ(g_failures, 1);

  // 注册顺序保持源码文件顺序
  CHECK(std::string(registry()[0].name) == "Norm");
  CHECK(std::string(registry()[3].name) == "Precision");

  return lab::report("14.1 测试体系");
}

本机实测(Apple clang,clang++ -std=c++20 -Wall):编译零警告,断言 10/10 通过。

小结

  • OGRE 测试分三层:单元测试(gtest)、渲染一致性(VisualTests)、模糊回归(fuzz),各有独立目录与驱动。
  • Tests/CMakeLists.txt 用 OGRE_BUILD_TESTS 门控,file(DOWNLOAD) 锁定 googletest 1.16.0,ENABLE_TESTING() 接入 CTest。
  • 单元测试用 TEST(Suite, Name) 定义用例,EXPECT_NEAR 用容差断言浮点,GTEST_SKIP() 把「不适用」与「失败」区分开。
  • 数据驱动测试用「表驱动」:一张 from/to 数组配一段循环代码即可展开多个测试实例。
  • 失败不中断同用例后续断言,最后统一汇总失败数——这是测试能暴露多问题的关键设计。

阅读导航:上一节:13.3 对象数据布局 · 下一节:14.2 渲染一致性测试 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图