Tesseract OCR 单元测试指南：数据布局、字体依赖与 make check 全流程解析

本文以 unittest/README.md 为蓝本，系统讲解 Tesseract 开源 OCR 引擎单元测试体系：测试数据仓库的四层目录布局、七类字体的依赖关系、make check 前的完整准备步骤，并结合 Makefile.am 与 CMakeLists.txt 的构建逻辑，说明测试二进制如何定位测试图片（TESTING_DIR 宏）、如何链接 vendored 版 googletest，以及如何抑制 fontconfig/freetype 的误报内存泄漏。读完后你能够独立搭建 Tesseract 单测环境、运行全部单元/集成测试并读懂其构建配置。

一、unittest 目录：测试用例的组织方式

Tesseract 将全部测试代码集中在 unittest/ 目录下，与主源码（src/）分离。从目录结构看，测试按被测模块命名，覆盖面包括：

• API 层：baseapi_test.cc、apiexample_test.cc、baseapi_thread_test.cc（多线程安全）、resultiterator_test.cc、capiexample_test.cc 与 capiexample_c_test.c（C/C++ 双接口）；
• 识别与语言模型：lstm_test.cc、recodebeam_test.cc、lang_model_test.cc、loadlang_test.cc、dawg_test.cc；
• 版面分析：equationdetect_test.cc、tablefind_test.cc、tablerecog_test.cc、paragraphs_test.cc、osd_test.cc、pagesegmode_test.cc；
• 基础数据结构与工具：bitvector_test.cc、matrix_test.cc、unicharset_test.cc、unicharcompress_test.cc、qrsequence_test.cc 等。

除 .cc 测试文件外，目录内还有几类支撑文件：

文件	作用
include_gunit.h	测试可移植性头文件，适配 Google 测试环境（见下文）
log.h、cycletimer.h、doubleptr.h	测试内部通用小工具
util/utf8/	Unicode/UTF-8 辅助库，供 tatweel_test.cc 等文本规范化测试使用
third_party/googletest/	vendored 的 googletest（git 子模块），测试框架本体
tesseract_leaksanitizer.supp	LeakSanitizer 泄漏抑制列表
fuzzers/	面向 OSS-Fuzz 的模糊测试入口 fuzzer-api.cpp

二、可移植性层：include_gunit.h 做了什么

include_gunit.h 是多数测试文件的公共头，它解决的是"测试代码沿用 Google 内部写法、却要在开源环境编译"的适配问题：

1. file 辅助类（include_gunit.h#L36-L72）：继承自 tesseract 自身的 tesseract::File（来自 src/training/unicharset/fileio.h），把 Google 风格的 WriteStringToFile、GetContents、JoinPath 接口桥接到开源实现上，并定义了临时目录标志 FLAGS_test_tmpdir = "./tmp"（include_gunit.h#L21），MakeTmpdir() 会在运行测试时创建该目录；
2. CHECK 宏族（include_gunit.h#L75-L85）：当环境未定义 CHECK 时，基于 LOG(FATAL) 提供 CHECK/CHECK_EQ/CHECK_GE 等比较断言宏，与 gtest 共存而不冲突。

也就是说，每个 *_test.cc 本质上是一个链接了 gtest 的独立可执行程序，由构建系统统一注册到 make check 中（下一节展开）。

三、运行测试前必须准备的资源：数据目录与字体

单元测试不只是跑代码，大量用例依赖真实扫描图像、多语言 traineddata 和训练数据目录。这些资源不在主仓库内，而是由外部数据集仓库提供。unittest/README.md 给出的目标布局如下（tesseract 为主仓库，langdata_lstm、tessdata* 与其并列）：

├── langdata_lstm
│   ├── common.punc
│   ├── common.unicharambigs
│   ├── desired_bigrams.txt
│   ├── eng
│   │   ├── desired_characters
│   │   ├── eng.config
│   │   ├── eng.numbers
│   │   ├── eng.punc
│   │   ├── eng.singles_text
│   │   ├── eng.training_text
│   │   ├── eng.unicharambigs
│   │   ├── eng.wordlist
│   │   └── okfonts.txt
│   ├── extended
│   │   └── extended.config
│   ├── extendedhin
│   │   └── extendedhin.config
│   ├── font_properties
│   ├── forbidden_characters_default
│   ├── hin
│   │   ├── hin.config
│   │   ├── hin.numbers
│   │   ├── hin.punc
│   │   └── hin.wordlist
│   ├── kan
│   │   └── kan.config
│   ├── kor
│   │   └── kor.config
│   ├── osd
│   │   └── osd.unicharset
│   └── radical-stroke.txt
├── tessdata
│   ├── ara.traineddata
│   ├── chi_tra.traineddata
│   ├── eng.traineddata
│   ├── heb.traineddata
│   ├── hin.traineddata
│   ├── jpn.traineddata
│   ├── kmr.traineddata
│   ├── osd.traineddata
│   └── vie.traineddata
├── tessdata_best
│   ├── eng.traineddata
│   ├── fra.traineddata
│   ├── kmr.traineddata
│   └── osd.traineddata
├── tessdata_fast
│   ├── eng.traineddata
│   ├── kmr.traineddata
│   ├── osd.traineddata
│   └── script
│       └── Latin.traineddata
└── tesseract
    ...
    ├── test
    ├── unittest
    │   └── third_party/googletest
    └── VERSION

各数据目录的用途可以从测试代码反推：

• tessdata/：九种语言的完整 traineddata，供 loadlang_test.cc、osd_test.cc 等多语言识别用例加载；osd.traineddata 单独承担方向/脚本检测（OSD）功能；
• tessdata_best/ 与 tessdata_fast/：不同质量的模型档位，script/Latin.traineddata 是整脚本（script）级模型；这些差异用于验证不同模型档位下识别路径的行为；
• langdata_lstm/：LSTM 训练侧数据（字符表、标点表、bigram、font_properties 等），供 lstmtrainer_test.cc、mastertrainer_test.cc 等训练器测试使用；
• test/testing/：主仓库内存放测试图像与 ground truth 文本的目录，由数据集仓库的 fonts 与图像资源拷贝而来（详见下节的准备命令）。

字体依赖

部分用例需要指定字体渲染文本或按字体断言，unittest/README.md 列出的字体共五类七件：

• 微软核心字体：arialbi.ttf、times.ttf、verdana.ttf（Linux 上通常通过 corefonts 系列工具安装）；
• 阿拉伯字体：ae_Arab.ttf；
• DejaVu 扩展字体：DejaVuSans-ExtraLight.ttf（用于覆盖大字符集，如 Devanagari 等）；
• 天城体（印地语）字体：Lohit-Hindi.ttf；
• 韩文字体：UnBatang.ttf。

这些字体的语言覆盖面（拉丁、阿拉伯、天城、谚文）与 tessdata/ 中的语种组合高度对应——hin、heb/ara、kor 等训练数据正是为这些字体渲染的文本服务的。

四、运行测试的完整步骤（README 原始命令链）

unittest/README.md 给出的操作序列是（在主仓库 tesseract 目录内执行）：

autoreconf -fiv                          # 重新生成 autotools 构建脚本
git submodule update --init             # 初始化 vendored 的 googletest 子模块
# 浅克隆单元测试数据集仓库（egorpugin/tessdata），落到 tessdata_unittest 目录
cp tessdata_unittest/fonts/* test/testing/   # 字体拷入 test/testing/
mv tessdata_unittest/* ../                 # 数据目录移到仓库同级（见上方目录布局）
export TESSDATA_PREFIX=/prefix/to/path/to/tessdata  # 指向数据目录
make check                                # 构建并运行全部测试

逐条说明：

1. autoreconf -fiv：仓库使用 autotools（configure.ac、Makefile.am），克隆后需先重新生成 configure；
2. git submodule update --init：Makefile.am#L1139-L1154 中静态列出了 libgtest_la、libgtest_main_la、libgmock_la、libgmock_main_la 四个库，其源码即 unittest/third_party/googletest/ 下的 gtest-all.cc、gtest_main.cc、gmock-all.cc、gmock_main.cc——子模块不初始化则这些目标缺源文件、构建失败；
3. 克隆数据集并布局：cp 将字体放入 test/testing/（与 Makefile.am#L1090-L1092 中 TESTING_DIR 指向的 test/testing 对应），mv 把 tessdata、tessdata_best、tessdata_fast、langdata_lstm 移到仓库的上一级目录，形成第三节开头的并列布局；
4. TESSDATA_PREFIX：运行时让引擎找到 tessdata/ 的根。注意它与编译期内置前缀不同——autotools 构建通过 --with-tessdata-prefix（默认 yes）把 -DTESSDATA_PREFIX='"@datadir@"' 注入编译宏（见 configure.ac#L341-L343 及 Makefile.am#L359-L360），而测试时优先使用环境变量指向本地数据集；
5. make check：autotools 约定，先构建 check_PROGRAMS 中注册的全部测试二进制（Makefile.am#L1168-L1262 中从 apiexample_test 到 unicharset_test 逐一登记），再逐个执行。

五、构建系统如何把测试接进来：TESTING_DIR 与注册机制

从 Makefile.am 的结构看，测试的接法是三步：

1. 注入图片根目录宏。 构建时计算测试图片绝对路径并编译进每个测试二进制：

# Makefile.am (L1090-L1092, L1104)
# Absolute path of directory 'testing' with test images and ground truth texts
TESTING_DIR=$(shell cd $(top_srcdir) && pwd)/test/testing
...
unittest_CPPFLAGS += -DTESTING_DIR="\"$(TESTING_DIR)\""

2. 以参数化/独立可执行程序形式注册。 每个用例文件对应一个 check_PROGRAMS 条目与一组 _SOURCES，例如 Makefile.am#L1266 的 apiexample_test_SOURCES = unittest/apiexample_test.cc，最终 TESTS = $(check_PROGRAMS)（Makefile.am#L1262）交给 autotools 的 check 目标统一调度。

3. 测试代码通过 TESTING_DIR 加载资源。 例如 baseapi_test.cc#L58 用 file::JoinPath(TESTING_DIR, name) 拼接图像名，osd_test.cc 的参数化用例直接引用 TESTING_DIR "/phototest.tif"、eurotext.tif、hebrew.png、devatest.png 等样本图——这也解释了为什么字体与图像必须先落到 test/testing/。

CMake 路径的对应关系

若改用 CMake 构建，CMakeLists.txt 提供了对应的开关：BUILD_TESTS 选项默认 OFF（CMakeLists.txt#L96），开启后在 CMakeLists.txt#L897-L902 处检测 unittest/third_party/googletest/CMakeLists.txt 是否存在（即子模块是否已初始化），存在才 add_subdirectory。因此 CMake 下跑测试的前提与 autotools 一致：初始化 googletest 子模块 + 准备 test/testing/ 资源 + 设置 TESSDATA_PREFIX。

六、运行时的内存泄漏抑制：LeakSanitizer 配置

多语言字体渲染测试会经由 fontconfig/freetype 加载字体，这两个库在进程退出时会留下被误报的"泄漏"。仓库为此提供了抑制文件 unittest/tesseract_leaksanitizer.supp，其内容针对 FcLangSetCreate、libfontconfig.so、libfreetype.so 等符号声明 leak: 抑制规则，并注释了用法：以 LSAN_OPTIONS=suppressions=tesseract_lsan.supp 运行测试。若你观察到 gtest 报告中出现 fontconfig 相关泄漏计数，可先对照该文件确认是否为已知误报。

七、小结与可验证要点

• 单测数据布局（tessdata* + langdata_lstm + test/testing/）与 TESSDATA_PREFIX 是运行测试的前置硬性条件，全部定义于 unittest/README.md；
• 构建接入证据链：TESTING_DIR 宏（Makefile.am#L1090-L1104）→ gtest 四个库（Makefile.am#L1139-L1154）→ check_PROGRAMS 注册表（Makefile.am#L1168-L1262）；
• 可移植层 include_gunit.h 解释了测试为何能同时使用 Google 风格接口与 tesseract 的 File/日志设施；
• CMake 用户需打开 BUILD_TESTS 并初始化子模块（CMakeLists.txt#L897-L902）；
• 泄漏误报处理见 unittest/tesseract_leaksanitizer.supp。

完成上述准备后，make check 即可在本地复现完整测试套件，这也是验证你对识别管线（API、LSTM、版面分析、语言模型）所做任何修改是否引入回归的标准方式。