PDF.js 字体测试指南基于 fonttools/ttx 的字体数据正确性验证体系【免费下载链接】pdf.jsPDF Reader in JavaScript项目地址: https://gitcode.com/gh_mirrors/pd/pdf.js本文讲解 PDF.js 仓库中test/font/目录下的字体测试Font tests机制它如何借助 Pythonfonttools库中的ttx工具以“PDF.js 读字体 → ttx 反读校验”的双向闭环验证 PDF.js 解析字体数据时不会产生破坏性变换。读完本文你将掌握字体测试的定位、npx gulp fonttest的本地运行方法、测试套件的文件构成与各 spec 的断言策略并能基于 test/font/README.md 与源码复现、扩展这类测试。字体测试的定位为什么需要一套独立的字体校验PDF 中的字体数据TrueType、OpenType/CFF、CIDFontType2 等是渲染正确性的基础。PDF.js 在src/core/fonts.js等模块中负责解析 PDF 字体字典、读取并必要时重写字体表。一旦解析或重写逻辑出错轻则字形错乱重则字体完全不可渲染。test/font/下的字体测试专门回答一个问题PDF.js 读取字体数据后是否仍然是一份可以被标准字体工具正确解析的合法字体。它不关心字形画得对不对而是从“字体文件本身是否自洽”这一底层维度做验证与test/unit/、test/integration/互补。工作原理PDF.js 解析与 ttx 反读的双向验证闭环根据 README.md 的说明字体测试的核心思路是让 PDF.js 读取构造Font对象解析内嵌在测试用例中的字体二进制数据把 PDF.js 处理后的字体数据交给ttx工具ttx来自 Pythonfonttools库把字体数据转换为便于断言的 XML 格式测试通过的标准是PDF.js 能成功读取字体数据且ttx能成功读回 PDF.js 处理后的字体数据——这证明 PDF.js 没有应用任何会破坏字体数据的变换。这一闭环在源码中对应三条明确路径浏览器端发起请求fontutils.js 中的ttx(data)通过fetch(/ttx, { method: POST, body: data.toBase64() })把字体数据以 Base64 形式发送给测试服务器。服务端转发到 ttxttxdriver.mjs 中的translateFont(content)将 Base64 解码为二进制写入系统临时目录下的pdfjs-font-test-{taskId}.otf文件因为 TTX 只接受文件作为输入然后spawn(ttx, [fontPath])调用命令行工具最后读取生成的.ttxXML 并清理临时文件。统一错误包装test/test.mjs 中的/ttxPOST 处理器调用translateFont若成功返回text/xml若失败则返回error.../error包装的错误浏览器端 fontutils.js 的verifyTtxOutput(output)正是通过识别error前缀来判定 ttx 反读失败。也就是说“ttx 能读回”这一结论在测试里被编码成了两个可断言的信号响应 XML 以error开头则失败否则继续用正则匹配ttFont//ttFont等 XML 结构。测试套件构成运行器与五个 spec 文件字体测试基于 Jasmine 框架运行入口是 font_test.html它通过script typeimportmap把pdfjs/映射到../../src/并加载 jasmine-boot.js。jasmine-boot.js 异步导入五个 spec 文件Spec 文件测试对象典型断言font_core_spec.js测试脚手架本身输出必须包含ttFont与/ttFont验证 ttx 链路可用font_fpgm_spec.jsfpgm 表字体 hinting 程序修复fpgm表在函数中间被截断时PDF.js 修复后 ttx 输出中 assembly 以ENDF[]/SVTCA[0]正常收尾font_glyf_spec.jsglyf 表字形轮廓自引用复合字形 0issue 21298被移除OS/2 表长度与声明版本不符时被重写为 version 3font_os2_spec.jsOS/2 表post 表值非法导致 OS/2 表被移除并重写断言OS_2内出现version value3/font_post_spec.jspost 表非法版本号、非法字形名索引、字形数量不符时post 表被改写为formatType3.0每个 spec 都遵循同一模式把内嵌的 Base64 字体数据包装成Uint8Array用 src/core/stream.js 的Stream、src/core/fonts.js 的Font构造 PDF.js 侧字体对象CIDFontType2 字体还需 src/core/cmap.js 的CMapFactory创建 Identity-H 编码以及 src/core/to_unicode_map.js 的ToUnicodeMap然后await ttx(font.data)拿到 XML最后用正则断言关键结构。以 font_glyf_spec.js 为例它演示了如何构造“坏字体”通过getTables解析字体目录定位glyf表偏移将第 0 个复合字形清零并写入自引用标志再交给Font处理最后断言 ttx 输出中的.notdef字形不再包含指向自身的component——这是一个完整的“注入缺陷 → 验证修复”测试范式。依赖安装与本地运行README 明确指出运行字体测试需要系统已安装以下依赖的稳定版本Python 3fonttools提供ttx命令行工具推荐的安装方式是使用pip在虚拟环境中安装fonttools这样可以避免系统级安装、提升环境隔离性。当然任何能让ttx出现在PATH环境变量中的安装方式都是可行的例如直接pip install fonttools到用户目录。按 README 给出的虚拟环境方式本地运行字体测试的完整命令序列如下python3 -m venv venv source venv/bin/activate pip install fonttools npx gulp fonttest其中npx gulp fonttest对应 gulpfile.mjs 中注册的fonttest任务它本质上是在启动test/test.mjs时传入--fontTest选项。在 test/test.mjs 中可以看到} else if (options.fontTest) { await startUnitTest(/test/font/font_test.html, font); }即--fontTest模式会启动本地测试服务器并打开test/font/font_test.html页面浏览器端的 Jasmine 用例通过/ttx接口与服务器上的ttx命令交互。同时 test/test.mjs 规定--reftest、--unitTest、--fontTest与--masterMode互斥不能同时指定。补充字体测试同样被集成在 CI 中运行。README 说明它通过 GitHub Actions 的工作流执行对应.github/workflows/font_tests.yml该目录通常存在于上游仓库根目录。故障排查ttx 不可用如果环境中没有安装fonttools服务端translateFont会在spawn(ttx, ...)触发error事件时抛出错误错误信息为Unable to execute ttx; make sure the fonttools dependency is installed浏览器端则表现为verifyTtxOutput捕获到error包装测试失败。因此遇到“所有字体测试统一失败”时第一排查项就是确认ttx是否在PATH中可在激活虚拟环境后执行which ttx验证。深入理解断言依赖 ttx 的 XML 输出字体测试的正确性最终落在“对 ttx XML 的正则断言”上这意味着断言内容与字体表结构强相关。理解几个常见断言能帮你快速定位失败原因脚手架自检font_core_spec.js/ttFont /与/\/ttFont/同时出现说明 ttx 成功解析并生成了标准 XML 骨架fpgm 修复验证font_fpgm_spec.js匹配/assembly/fpgm前的ENDF[]/SVTCA[0]确认被截断的 TrueType 指令程序被正确截断为完整指令OS/2 重写验证font_os2_spec.js匹配version value3/并进一步检查sCapHeight、usMaxContext等 v3 字段的存在post 表回退验证font_post_spec.js匹配formatType value3.0/确认 post 表被回退到无字形名索引的格式 3.0。从这些断言可以推断字体测试不只做“能不能读”的冒烟验证还覆盖了 PDF.js 在src/core/fonts.js中对异常字体表的主动修复/重写行为——这正是它作为回归测试的价值所在。扩展阅读测试脚手架客户端与错误约定test/font/fontutils.jsttx 服务端驱动临时文件、进程调用、清理逻辑test/font/ttxdriver.mjs被测字体解析入口src/core/fonts.js、src/core/stream.js、src/core/cmap.js运行入口与参数约束test/test.mjs、gulpfile.mjs小结PDF.js 的字体测试以ttxfonttools为独立裁判构建了“PDF.js 解析 → 生成临时字体文件 → ttx 反读 → XML 断言”的验证闭环。它既验证 PDF.js 能读字体也验证读完之后字体仍是合法的、可被标准工具消费的数据从而为字体解析与表修复逻辑提供了精准的回归保护。本地运行只需 Python 3 fonttoolsnpx gulp fonttest一条链路故障时优先排查ttx是否可执行即可。【免费下载链接】pdf.jsPDF Reader in JavaScript项目地址: https://gitcode.com/gh_mirrors/pd/pdf.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PDF.js 字体测试指南：基于 fonttools/ttx 的字体数据正确性验证体系
PDF.js 字体测试指南基于 fonttools/ttx 的字体数据正确性验证体系【免费下载链接】pdf.jsPDF Reader in JavaScript项目地址: https://gitcode.com/gh_mirrors/pd/pdf.js本文讲解 PDF.js 仓库中test/font/目录下的字体测试Font tests机制它如何借助 Pythonfonttools库中的ttx工具以“PDF.js 读字体 → ttx 反读校验”的双向闭环验证 PDF.js 解析字体数据时不会产生破坏性变换。读完本文你将掌握字体测试的定位、npx gulp fonttest的本地运行方法、测试套件的文件构成与各 spec 的断言策略并能基于 test/font/README.md 与源码复现、扩展这类测试。字体测试的定位为什么需要一套独立的字体校验PDF 中的字体数据TrueType、OpenType/CFF、CIDFontType2 等是渲染正确性的基础。PDF.js 在src/core/fonts.js等模块中负责解析 PDF 字体字典、读取并必要时重写字体表。一旦解析或重写逻辑出错轻则字形错乱重则字体完全不可渲染。test/font/下的字体测试专门回答一个问题PDF.js 读取字体数据后是否仍然是一份可以被标准字体工具正确解析的合法字体。它不关心字形画得对不对而是从“字体文件本身是否自洽”这一底层维度做验证与test/unit/、test/integration/互补。工作原理PDF.js 解析与 ttx 反读的双向验证闭环根据 README.md 的说明字体测试的核心思路是让 PDF.js 读取构造Font对象解析内嵌在测试用例中的字体二进制数据把 PDF.js 处理后的字体数据交给ttx工具ttx来自 Pythonfonttools库把字体数据转换为便于断言的 XML 格式测试通过的标准是PDF.js 能成功读取字体数据且ttx能成功读回 PDF.js 处理后的字体数据——这证明 PDF.js 没有应用任何会破坏字体数据的变换。这一闭环在源码中对应三条明确路径浏览器端发起请求fontutils.js 中的ttx(data)通过fetch(/ttx, { method: POST, body: data.toBase64() })把字体数据以 Base64 形式发送给测试服务器。服务端转发到 ttxttxdriver.mjs 中的translateFont(content)将 Base64 解码为二进制写入系统临时目录下的pdfjs-font-test-{taskId}.otf文件因为 TTX 只接受文件作为输入然后spawn(ttx, [fontPath])调用命令行工具最后读取生成的.ttxXML 并清理临时文件。统一错误包装test/test.mjs 中的/ttxPOST 处理器调用translateFont若成功返回text/xml若失败则返回error.../error包装的错误浏览器端 fontutils.js 的verifyTtxOutput(output)正是通过识别error前缀来判定 ttx 反读失败。也就是说“ttx 能读回”这一结论在测试里被编码成了两个可断言的信号响应 XML 以error开头则失败否则继续用正则匹配ttFont//ttFont等 XML 结构。测试套件构成运行器与五个 spec 文件字体测试基于 Jasmine 框架运行入口是 font_test.html它通过script typeimportmap把pdfjs/映射到../../src/并加载 jasmine-boot.js。jasmine-boot.js 异步导入五个 spec 文件Spec 文件测试对象典型断言font_core_spec.js测试脚手架本身输出必须包含ttFont与/ttFont验证 ttx 链路可用font_fpgm_spec.jsfpgm 表字体 hinting 程序修复fpgm表在函数中间被截断时PDF.js 修复后 ttx 输出中 assembly 以ENDF[]/SVTCA[0]正常收尾font_glyf_spec.jsglyf 表字形轮廓自引用复合字形 0issue 21298被移除OS/2 表长度与声明版本不符时被重写为 version 3font_os2_spec.jsOS/2 表post 表值非法导致 OS/2 表被移除并重写断言OS_2内出现version value3/font_post_spec.jspost 表非法版本号、非法字形名索引、字形数量不符时post 表被改写为formatType3.0每个 spec 都遵循同一模式把内嵌的 Base64 字体数据包装成Uint8Array用 src/core/stream.js 的Stream、src/core/fonts.js 的Font构造 PDF.js 侧字体对象CIDFontType2 字体还需 src/core/cmap.js 的CMapFactory创建 Identity-H 编码以及 src/core/to_unicode_map.js 的ToUnicodeMap然后await ttx(font.data)拿到 XML最后用正则断言关键结构。以 font_glyf_spec.js 为例它演示了如何构造“坏字体”通过getTables解析字体目录定位glyf表偏移将第 0 个复合字形清零并写入自引用标志再交给Font处理最后断言 ttx 输出中的.notdef字形不再包含指向自身的component——这是一个完整的“注入缺陷 → 验证修复”测试范式。依赖安装与本地运行README 明确指出运行字体测试需要系统已安装以下依赖的稳定版本Python 3fonttools提供ttx命令行工具推荐的安装方式是使用pip在虚拟环境中安装fonttools这样可以避免系统级安装、提升环境隔离性。当然任何能让ttx出现在PATH环境变量中的安装方式都是可行的例如直接pip install fonttools到用户目录。按 README 给出的虚拟环境方式本地运行字体测试的完整命令序列如下python3 -m venv venv source venv/bin/activate pip install fonttools npx gulp fonttest其中npx gulp fonttest对应 gulpfile.mjs 中注册的fonttest任务它本质上是在启动test/test.mjs时传入--fontTest选项。在 test/test.mjs 中可以看到} else if (options.fontTest) { await startUnitTest(/test/font/font_test.html, font); }即--fontTest模式会启动本地测试服务器并打开test/font/font_test.html页面浏览器端的 Jasmine 用例通过/ttx接口与服务器上的ttx命令交互。同时 test/test.mjs 规定--reftest、--unitTest、--fontTest与--masterMode互斥不能同时指定。补充字体测试同样被集成在 CI 中运行。README 说明它通过 GitHub Actions 的工作流执行对应.github/workflows/font_tests.yml该目录通常存在于上游仓库根目录。故障排查ttx 不可用如果环境中没有安装fonttools服务端translateFont会在spawn(ttx, ...)触发error事件时抛出错误错误信息为Unable to execute ttx; make sure the fonttools dependency is installed浏览器端则表现为verifyTtxOutput捕获到error包装测试失败。因此遇到“所有字体测试统一失败”时第一排查项就是确认ttx是否在PATH中可在激活虚拟环境后执行which ttx验证。深入理解断言依赖 ttx 的 XML 输出字体测试的正确性最终落在“对 ttx XML 的正则断言”上这意味着断言内容与字体表结构强相关。理解几个常见断言能帮你快速定位失败原因脚手架自检font_core_spec.js/ttFont /与/\/ttFont/同时出现说明 ttx 成功解析并生成了标准 XML 骨架fpgm 修复验证font_fpgm_spec.js匹配/assembly/fpgm前的ENDF[]/SVTCA[0]确认被截断的 TrueType 指令程序被正确截断为完整指令OS/2 重写验证font_os2_spec.js匹配version value3/并进一步检查sCapHeight、usMaxContext等 v3 字段的存在post 表回退验证font_post_spec.js匹配formatType value3.0/确认 post 表被回退到无字形名索引的格式 3.0。从这些断言可以推断字体测试不只做“能不能读”的冒烟验证还覆盖了 PDF.js 在src/core/fonts.js中对异常字体表的主动修复/重写行为——这正是它作为回归测试的价值所在。扩展阅读测试脚手架客户端与错误约定test/font/fontutils.jsttx 服务端驱动临时文件、进程调用、清理逻辑test/font/ttxdriver.mjs被测字体解析入口src/core/fonts.js、src/core/stream.js、src/core/cmap.js运行入口与参数约束test/test.mjs、gulpfile.mjs小结PDF.js 的字体测试以ttxfonttools为独立裁判构建了“PDF.js 解析 → 生成临时字体文件 → ttx 反读 → XML 断言”的验证闭环。它既验证 PDF.js 能读字体也验证读完之后字体仍是合法的、可被标准工具消费的数据从而为字体解析与表修复逻辑提供了精准的回归保护。本地运行只需 Python 3 fonttoolsnpx gulp fonttest一条链路故障时优先排查ttx是否可执行即可。【免费下载链接】pdf.jsPDF Reader in JavaScript项目地址: https://gitcode.com/gh_mirrors/pd/pdf.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考