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 渲染一致性测试 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。