14.3 回归与验证
测试体系再完整,也挡不住两类「漏网之鱼」:运行期前置条件被破坏(调用方传了非法参数)和外部输入不合法(磁盘上被人篡改过的资源文件、网络来的畸形数据)。前者靠断言在出错的当场喊停,后者靠模糊测试在用户碰到之前把崩溃炸出来。这一节看 OGRE 的 OgreAssert/OgreAssertDbg 断言宏与 Tests/fuzz/ 的 libFuzzer 入口。
本章与站内既有内容的分工
helio 四卷在自研引擎里用过 assert 与自定义异常;这里解析真实 OGRE 的配置化断言——OGRE_ASSERT_MODE 一个宏控制全局「断言还是抛异常」,以及 fuzz 入口的「隔离预期的 Ogre::Exception」契约。14.1 讲的是怎么组织测试,本节讲怎么让断言与模糊测试成为回归的最后一道闸。
OgreAssert:三模式断言
OgreException.h 顶部用 OGRE_ASSERT_MODE 把断言行为切成三种,并额外提供只在 Debug 生效的 OgreAssertDbg:
// OgreMain/include/OgreException.h:OgreAssert / OgreAssertDbg 宏(v14.6.3 源码摘录,已删减)
// Check for OGRE assert mode
// RELEASE_EXCEPTIONS mode
#if OGRE_ASSERT_MODE == 1
# if OGRE_DEBUG_MODE
# define OgreAssert( a, b ) assert( (a) && (b) )
# else
# define OgreAssert( a, b ) if( !(a) ) OGRE_EXCEPT_2( Ogre::Exception::ERR_RT_ASSERTION_FAILED, (#a " failed. " b) )
# endif
// EXCEPTIONS mode
#elif OGRE_ASSERT_MODE == 2
# define OgreAssert( a, b ) if( !(a) ) OGRE_EXCEPT_2( Ogre::Exception::ERR_RT_ASSERTION_FAILED, (#a " failed. " b) )
// STANDARD mode
#else
# define OgreAssert( expr, mesg ) assert( (expr) && (mesg) )
#endif
#if OGRE_DEBUG_MODE
# define OgreAssertDbg( a, b ) OgreAssert( a, b )
#else
/// replaced with OgreAssert(expr, mesg) in Debug configuration
# define OgreAssertDbg( expr, mesg )
#endif
三种模式解决同一个问题的不同答案:「断言失败后怎么办?」
OGRE_ASSERT_MODE | Debug 行为 | Release 行为 | 适用场景 |
|---|---|---|---|
| 0(STANDARD) | assert 中止 | assert 中止(通常被 NDEBUG 关闭) | 开发期检查前置条件 |
| 1(RELEASE_EXCEPTIONS) | assert 中止 | OGRE_EXCEPT_2(ERR_RT_ASSERTION_FAILED, ...) 抛 RuntimeAssertionException | 发布版也要保护 |
| 2(EXCEPTIONS,默认) | 抛异常 | 抛异常 | 全程异常式错误处理 |
OgreAssertDbg 是「只在 Debug 检查」的断言:Debug 展开成 OgreAssert,Release 展开为空。典型用途是性能敏感但只在开发期有意义的检查——比如每帧的临时一致性校验,发布版直接跳过。
失败时抛的 ERR_RT_ASSERTION_FAILED 会转成 Ogre::RuntimeAssertionException,在 Exception 的 case 里可被上层 catch (Ogre::Exception&) 统一捕获(OgreException.h:268)。这样发布版的断言失败不是「程序死亡」,而是「可捕获、可记录、可降级」。
fuzz:让测试发现异常退出
断言守住了引擎内部的预期,但外部世界不按预期来。Tests/fuzz/ 用 libFuzzer 把随机字节喂给解析器,stream_fuzz.cpp 是典型入口:
// Tests/fuzz/stream_fuzz.cpp:LLVMFuzzerTestOneInput(v14.6.3 源码摘录,已删减)
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
Ogre::LogManager logManager;
logManager.createLog("Temporary log", true, true, true);
char filename[256];
sprintf(filename, "/tmp/libfuzzer.%d", getpid());
FILE *fp = fopen(filename, "wb");
if (!fp) {
return 0;
}
fwrite(data, size, 1, fp);
fclose(fp);
Ogre::String fileName = filename;
Ogre::FileSystemArchiveFactory factory;
Ogre::Archive *arch = factory.createInstance("/tmp/", false);
arch->load();
Ogre::DataStreamPtr stream = arch->open(fileName);
Ogre::StreamSerialiser serialiser(stream);
try {
serialiser.readChunkBegin();
Ogre::Vector3 dest;
serialiser.read(&dest, 1);
} catch (Ogre::Exception&) {
}
factory.destroyInstance(arch);
unlink(filename);
return 0;
}
这个入口展示了几条 fuzz 铁律:
- 输入落盘再读:把
data/size写进临时文件,再用 OGRE 的FileSystemArchive+DataStreamPtr走完整资源路径——测试的是「真实加载管线」,不是内存里的裸解析。 catch (Ogre::Exception&)包住解析:readChunkBegin()/read(&dest, 1)可能因畸形数据抛异常,但 fuzz 进程必须存活——异常被吞掉,libFuzzer 才能继续变异下一轮输入。崩溃只允许来自真实 bug(越界写、解引用空指针),不允许来自「可预期的解析失败」。- 返回值恒定
0:libFuzzer 只关心「是否崩溃」,return 0表示「这一轮输入没崩,请继续变异」。 - 临时文件自清理:
unlink(filename)收尾,不让 fuzz 跑几十万轮后把/tmp塞满。
fuzz/ 目录里还有 image_fuzz.cpp(图像解码)、script_fuzz.cpp(脚本解析)、zip_fuzz.cpp(压缩流)——每个都套同一个模板:写盘 → 走真实加载 → try/catch 吞异常 → 清理。
源码定位
OgreMain/include/OgreException.h:#if OGRE_ASSERT_MODE == 1(40)、#define OgreAssert( a, b ) assert( (a) && (b) )(42)、#define OgreAssert( a, b ) if( !(a) ) OGRE_EXCEPT_2(...)(44/49)、#define OgreAssert( expr, mesg ) assert( (expr) && (mesg) )(63)、#if OGRE_DEBUG_MODE/#define OgreAssertDbg( a, b ) OgreAssert( a, b )(66-67)、#define OgreAssertDbg( expr, mesg )(70)Tests/fuzz/stream_fuzz.cpp:extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)(31-64)、serialiser.readChunkBegin()(54)、serialiser.read(&dest, 1)(57)、catch (Ogre::Exception&)(58)、unlink(filename)(61)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现三模式断言与 fuzz 入口的预期解析异常的处理。它与 src/ogre-ext-14-3-regression-verification.cpp 逐字节一致:
// file: src/ogre-ext-14-3-regression-verification.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-14-3-regression-verification.cpp -o bin/ogre-ext-14-3-regression-verification && ./bin/ogre-ext-14-3-regression-verification
//
// 复现 OGRE 的回归验证双机制:
// OgreAssert/OgreAssertDbg 三模式(OgreException.h 40-71):
// STANDARD 返回失败、RELEASE_EXCEPTIONS 仅在 release 抛异常、
// EXCEPTIONS 恒抛异常、OgreAssertDbg 只在 debug 保留;
// fuzz 入口(Tests/fuzz/stream_fuzz.cpp 31-64):
// 任意字节输入都要能安全解析,异常不得逃逸出 LLVMFuzzerTestOneInput。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <cstring>
namespace ogre_repro {
// 对应 OGRE_ASSERT_MODE 三种模式:0=STANDARD 1=RELEASE_EXCEPTIONS 2=EXCEPTIONS
template <int Mode, bool Debug>
bool assertCheck(bool expr) {
if (expr) return true;
if (Mode == 1 && !Debug) throw 1; // RELEASE_EXCEPTIONS:release 抛异常
if (Mode == 2) throw 2; // EXCEPTIONS:恒抛异常
return false; // STANDARD / debug assert:返回失败
}
// 对应 OgreAssertDbg:只在 debug 配置保留检查
template <bool Debug>
bool dbgAssert(bool expr) {
if (!Debug) return true; // release 下展开为空操作
return assertCheck<1, true>(expr);
}
// 对应 StreamSerialiser 的最小子集:chunk 头 + 12 字节 Vector3
struct Serialiser {
const uint8_t* data;
size_t size;
size_t pos;
};
// 对应 serialiser.readChunkBegin()
bool readChunkBegin(Serialiser& s) {
if (s.size - s.pos < 4) return false;
s.pos += 4; // chunkId(2) + chunkSize(2)
return true;
}
// 对应 serialiser.read(&dest, 1):读 3 个 float
bool readVector3(Serialiser& s, float out[3]) {
if (s.size - s.pos < sizeof(float) * 3) return false;
std::memcpy(out, s.data + s.pos, sizeof(float) * 3);
s.pos += sizeof(float) * 3;
return true;
}
// 对应 stream_fuzz.cpp 的 LLVMFuzzerTestOneInput:在局部解析段捕获预期异常
int llvmFuzzerTestOneInput(const uint8_t* data, size_t size) {
Serialiser s{data, size, 0};
try {
if (!readChunkBegin(s)) return 0;
float v[3];
if (readVector3(s, v)) {
// 消费数据但不信任数值:NaN 断言失败走 debug 路径,异常不外逃
assertCheck<1, true>(v[0] == v[0]);
assertCheck<1, true>(v[1] == v[1]);
assertCheck<1, true>(v[2] == v[2]);
}
} catch (...) {
return 0; // 异常被吞掉,fuzz 进程不崩溃
}
return 0;
}
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// STANDARD 模式:失败返回 false,不抛
CHECK((!assertCheck<0, true>(false)));
CHECK((assertCheck<0, true>(true)));
// RELEASE_EXCEPTIONS + debug:失败返回 false(debug assert 语义)
CHECK((!assertCheck<1, true>(false)));
// RELEASE_EXCEPTIONS + release:失败抛异常
bool threw1 = false;
try {
assertCheck<1, false>(false);
} catch (int) {
threw1 = true;
}
CHECK(threw1);
// EXCEPTIONS 模式:debug 配置下也抛
bool threw2 = false;
try {
assertCheck<2, true>(false);
} catch (int) {
threw2 = true;
}
CHECK(threw2);
// OgreAssertDbg:debug 保留检查,release 空操作
CHECK((!dbgAssert<true>(false)));
CHECK((dbgAssert<false>(false)));
// fuzz 入口:合法输入安全返回
uint8_t good[16] = {0};
CHECK(llvmFuzzerTestOneInput(good, 16) == 0);
// 头都读不全的输入
uint8_t tiny[2] = {0, 0};
CHECK(llvmFuzzerTestOneInput(tiny, 2) == 0);
// 头后不足一个 Vector3
uint8_t junk[8] = {0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
CHECK(llvmFuzzerTestOneInput(junk, 8) == 0);
// 含 NaN 的 Vector3:断言失败但异常不逃逸
uint8_t nan[16] = {0, 0, 0, 0, 0, 0, 0xc0, 0x7f, 0, 0, 0, 0, 0, 0, 0, 0};
CHECK(llvmFuzzerTestOneInput(nan, 16) == 0);
// fuzz 入口返回值恒定 0(对应 libFuzzer 契约)
CHECK_EQ(llvmFuzzerTestOneInput(good, 16), 0);
return lab::report("14.3 回归与验证");
}
本机实测(Apple clang,clang++ -std=c++20 -Wall):编译零警告,断言 12/12 通过。
小结
OgreAssert由OGRE_ASSERT_MODE切成三模式:STANDARD 用assert、RELEASE_EXCEPTIONS 在 release 抛RuntimeAssertionException、EXCEPTIONS 恒抛。OgreAssertDbg只在 Debug 展开,Release 为空操作,适合「开发期才有意义」的每帧检查。- 断言失败在发布版可被
catch (Ogre::Exception&)捕获,错误处理可降级而不是程序死亡。 - fuzz 入口的铁律:输入落盘走真实加载管线、try/catch 吞掉可预期的解析异常、返回值恒 0、临时文件自清理。
- 断言守住「引擎内部前置条件」,fuzz 守住「外部输入不合法」,二者构成回归的最后一道闸。
阅读导航:上一节:14.2 渲染一致性测试 · 下一节:15.1 从源码到引擎 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。