Haxe 杂项测试套件解析:tests/misc 编译回归测试的约定、实现与本地运行指南
Haxe 杂项测试套件解析:tests/misc 编译回归测试的约定、实现与本地运行指南
Haxe 编译器的开发离不开一套覆盖面极广的回归测试体系,其中位于仓库根目录下的 tests/misc 杂项测试套件专门用于验证编译器对各类边界情况、历史 Issue 与语言特性的处理是否符合预期。本文以 tests/misc/README.md 为核心,结合 tests/misc/src/Main.hx 的测试驱动源码,系统讲解这套以 "hxml 工程 + 退出码 + stderr 比对" 为核心的测试约定,并给出完整可复现的本地运行命令,帮助你理解 Haxe 编译器测试的底层机制,甚至亲手为回归缺陷编写一个新测试工程。
一、tests/misc 是什么:一锅"编译器行为回归测试"
在 Haxe 仓库中,tests/misc 与 tests/unit(单元测试)、tests/optimization(优化测试)、tests/server(语言服务器测试)等并列,专门承载那些"难以归入某一目标平台统一框架"的杂项测试——它们通常以一个独立的最小 Haxe 工程(一个目录)为最小单元,验证某个具体的编译器行为:可能是某个历史 Issue 是否被修复、某个新语法特性是否按预期报错、某个宏在特定条件下是否正常工作。
从目录结构看(以 tests/misc 为例),其下按目标平台/场景分门别类:
tests/misc/eval/projects/:面向 eval 目标的工程集合,也是数量最庞大的一批(IssueXXXX编号目录数以百计);tests/misc/js/projects/、tests/misc/jvm/projects/、tests/misc/lua/projects/、tests/misc/neko/projects/、tests/misc/php/projects/、tests/misc/flash/projects/、tests/misc/hlc/projects/、tests/misc/cpp/projects/等:按目标平台划分的工程集合;tests/misc/python/projects/、tests/misc/hl/projects/:README 中特别指出的"目标特有"测试目录;tests/misc/src/:测试驱动的 Haxe 源码(Main.hx)与compile.hxml、run-base.hxml等入口配置;tests/misc/eval/connect_stdin/、tests/misc/js/es6/等:更复杂、需要额外运行步骤(如连接 stdin、跑 Node)的专项测试。
这套测试的核心思想非常朴素:编译成功即通过,编译失败则要求错误输出精确匹配。下面详细展开。
二、测试工程的组织约定:compile.hxml 与 compile-fail.hxml
根据 tests/misc/README.md,tests/misc/projects(以及各目标平台目录下的 projects 子目录)中的每个目录都是一个独立 Haxe 工程,在 CI 上执行宏测试套件(macro test suite)期间会被逐个单独执行。每个工程应当包含 compile.hxml 和/或 compile-fail.hxml,测试套件会查找这些文件并交给 Haxe 编译器处理。
2.1 成功型测试:compile.hxml
如果工程目录中存在 compile.hxml,套件执行 haxe compile.hxml;只要该命令以退出码 0 结束,测试即视为通过。例如 tests/misc/eval/projects/_semver/compile.hxml 配合 tests/misc/eval/projects/_semver/Main.hx,就是一个典型的"应能编译通过"用例。
2.2 失败型测试:compile-fail.hxml + .stderr 期望文件
如果存在 compile-fail.hxml,套件执行 haxe compile-fail.hxml,并把该命令的 stderr 与位于同目录下的 compile-fail.hxml.stderr 文件内容做精确比对;stderr 与期望文件一致,测试才算通过。这一机制用来锁定编译器错误信息文本——一旦某次改动改变了报错文案或行号,比对就会失败,从而暴露回归。
一个典型实例是 tests/misc/eval/projects/Issue10005,它的 compile-fail.hxml 只有一行 --main Main,对应的 Main.hx 故意写错 overload 修饰符的用法,而 compile-fail.hxml.stderr 精确记录了期望的错误输出:
Main.hx:5: characters 16-24 : Invalid modifier: overload is only supported on extern functions
2.3 一个目录多个测试:数字后缀约定
同一个工程目录下可以承载多个测试,只需给 hxml 文件加上数字后缀即可,测试套件会全部拾取执行:
compile1.hxml、compile2.hxml:多个"应编译成功"的测试;compile1-fail.hxml+compile1-fail.hxml.stderr、compile2-fail.hxml+compile2-fail.hxml.stderr:多个"应编译失败并精确匹配错误输出"的测试。
仓库中 tests/misc/eval/projects/trailing-commas 正是多测试一目录的范例:compile1.hxml(对应 --main Main)验证尾逗号合法、compile2-fail.hxml 与 compile3-fail.hxml(分别对应 --main Main2、--main Main3)验证不同位置出现多余逗号时编译器报出 Unexpected , 错误,各自的 compile2-fail.hxml.stderr 锁定期望错误信息。
三、测试驱动源码剖析:tests/misc/src/Main.hx 如何工作
README 描述的是"外部约定",而 tests/misc/src/Main.hx 揭示了这套约定的内部实现,值得逐段对照理解。
3.1 入口与整体流程
Main.main() 调用 compileProjects(Sys.args()),统计后打印 Done running ${count} tests with ${failures} failures,并以失败数作为进程退出码(Sys.exit(result.failures)),方便 CI 直接根据退出码判断成败;当测试数量超过 20 且存在失败时,还会额外输出 SUMMARY: 失败摘要。
compileProjects 的核心逻辑(Main.hx 第 26-71 行):
- 读取第一个参数作为
subdir,Sys.setCwd(subdir)切换到测试根目录; - 通过
Compiler.getDefine("MISC_TEST_FILTER")读取过滤条件并编译成正则表达式,缺省时匹配所有路径; - 递归浏览
projects目录(browse("projects")),遇到以.disabled结尾的目录则跳过并打印Skipping ...,这允许测试作者临时停用某工程; - 对每个
*.hxml文件(排除以-each.hxml结尾的文件)执行编译;若其路径匹配过滤正则,则:- 进入该文件所在目录、切换工作目录;
- 通过
file.endsWith("-fail.hxml")判断是否为"期望失败"测试; - 若存在同名的
.stdout/.stderr文件,加载为期望输出(经由prepareExpectedOutput模板化处理); - 以
haxe -D message.reporting=classic <file>形式启动编译器进程,并追加命令行传入的其余参数。
值得注意的是 -D message.reporting=classic:它强制 Haxe 使用经典的错误信息报告格式,避免新格式导致 stderr 比对不稳定。
3.2 运行与判定:runCommand 的状态机
runCommand(Main.hx 第 97-147 行)用 sys.io.Process 启动外部 haxe 进程,随后按"是否期望失败"组成一个四态判定:
| 实际退出码 | 期望失败 | 判定 | 说明 |
|---|---|---|---|
| 0 | 否 | 通过 | 编译成功且本就不期望失败 |
| 0 | 是 | 失败 | 打印 Expected failure, but no failure occurred |
| 非 0 | 是 | 通过 | 编译按预期失败 |
| 非 0 | 否 | 失败 | 打印 stderr 内容 |
如果测试通过且存在 .stdout 期望文件,则继续用 checkOutput 比对 stdout;同样,存在 .stderr 期望文件时比对 stderr。两个比对都通过,该测试才算真正成功。
该函数还支持 Linux 下的超时保护:当编译定义了 timeout 宏时,会改用系统 timeout 命令包裹 haxe(Main.hx 第 103-112 行),并把退出码 124 视为"超时失败",打印 Timeout. No response in ... seconds.。
3.3 输出比对:checkOutput 的智能归一化
checkOutput(Main.hx 第 149-187 行)绝不是简单的字符串相等,它做了多层容错处理,以保证跨平台、跨环境的稳定性:
- 统一把
\r\n归一化为\n,并trim两侧空白; - 过滤 JVM 偶尔输出的
Picked up JAVA_TOOL_OPTIONS: ...干扰行; - 对
{"jsonrpc":...}形式的输出尝试 JSON 解析、提取result.result后重新序列化,以消除字段顺序差异; - 调用
hideStdPositions(第 189-195 行)将 std 库中报错位置的正则替换为???:,避免因标准库路径在不同机器/平台不同而导致误报; - 仍不一致时,借助
tests/tools/diff(即tests/misc/run-base.hxml中-p ../tools引入的 diff 工具库)生成并打印 unified diff,方便开发者一眼定位期望输出与实际输出的差异。
prepareExpectedOutput(第 73-83 行)则通过 haxe.Template 支持在 .stderr 期望文件中嵌入 $cwd(当前工作目录)与 $std(标准库路径)等模板变量,并用 normPath 宏在 Windows 下将路径统一为"大写盘符 + 反斜杠"形式,从而让期望文件在不同操作系统上都能匹配。
3.4 入口配置:compile.hxml 与 run-base.hxml
tests/misc/compile.hxml 是套件的总入口,内容如下:
run-base.hxml
#-D MISC_TEST_FILTER=4270
--run Main
eval
它先引用 tests/misc/run-base.hxml(设置 -p src 与 -p ../tools 两个源码路径),再以 --run Main 执行入口,并选择 eval 目标运行——也就是说,整个测试驱动程序本身是用 Haxe 的 eval 目标解释执行的,无需预编译。#-D MISC_TEST_FILTER=4270 是被注释掉的过滤示例,取消注释即可只跑 Issue4270 对应的工程。
四、在本地运行 tests/misc 测试
4.1 运行全部工程测试
按 README 说明,进入 tests/misc 目录后执行:
cd tests/misc
haxe compile.hxml
程序会递归扫描所有 projects 目录下的 hxml 工程并逐个编译验证,最终打印 Done running N tests with M failures 并以失败数作为退出码。若 M 大于 0,shell 的 $? 也为非零,可直接用于 CI 脚本判断。
4.2 只运行单个工程:MISC_TEST_FILTER
开发时往往只想验证某个 Issue 是否修复,此时用 -D MISC_TEST_FILTER 指定目录名中的数字:
haxe -D MISC_TEST_FILTER=1234 compile.hxml
其中 1234 取自工程目录名 Issue1234。过滤器实现于 Main.hx 第 35-36 行:MISC_TEST_FILTER 被编译成正则表达式,与每个 hxml 文件的完整路径做匹配(第 48 行的 filterRegex.match(path))。由于匹配的是正则而非子串,你还可以使用 1000、Issue10.* 等更灵活的模式来一次匹配多个工程。
4.3 运行目标专属测试
部分目标平台的测试放在独立目录中,README 明确点名了 tests/misc/python 与 tests/misc/hl(前者在仓库中进一步细分为 projects/ 与 pythonImport/)。运行方式是在目标目录下执行:
cd tests/misc/python # 或 tests/misc/hl
haxe run.hxml
同样支持单工程过滤:
haxe -D MISC_TEST_FILTER=1234 run.hxml
需要注意:这类 run.hxml 由各目标目录自行维护,结构与功能不尽相同,实际内容以当前仓库该目录下的文件为准。例如 tests/misc/js/es6/run.hxml 展示了"编译 + 运行"一体的形态:
-main Test
-js test.js
-D js-es=6
-cmd node test.js
它先用 Haxe 把 tests/misc/js/es6/Test.hx 编译成 ES6 的 test.js,再通过 -cmd node test.js 交给 Node 实际执行并校验行为,属于比"仅编译"更进一步的运行期测试。此外 tests/misc/eval/connect_stdin/ 也拥有自己的 run.hxml,用于验证 eval 目标与标准输入交互等复杂场景。
五、实战:如何为一个回归缺陷新增测试工程
理解了约定之后,为编译器新增回归测试就变成一件标准化的工作:
- 在合适的位置建目录:通用行为放
tests/misc/eval/projects/IssueXXXX/;平台相关行为放对应平台的projects/目录;特殊情况(如需要运行期验证)参考tests/misc/js/es6/、tests/misc/eval/connect_stdin/的组织方式。 - 编写最小复现的 Haxe 源码:比如
Main.hx,仅保留触发缺陷的最小代码。 - 编写 hxml:修复类测试写
compile.hxml(如--main Main),验证报错类测试写compile-fail.hxml。 - 生成期望输出:先直接运行
haxe -D message.reporting=classic compile-fail.hxml,把 stderr 重定向保存为compile-fail.hxml.stderr;Main.hx会对换行、路径、JVM 噪声等做归一化,因此保存时保持原样即可。 - 本地验证:
cd tests/misc && haxe -D MISC_TEST_FILTER=XXXX compile.hxml,确认输出Done running 1 tests with 0 failures。 - 需要多场景时使用数字后缀:参考
tests/misc/eval/projects/trailing-commas/的compile1.hxml/compile2-fail.hxml/compile3-fail.hxml命名。 - 临时停用某工程:把工程目录改名为
XXX.disabled结尾(例如Issue2278.disabled、Pull12231.disabled这类形态在仓库中真实存在),套件会自动跳过。
六、与 CI 的衔接:退出码即结论
整套设计的最后一块拼图是 CI 集成。由于 tests/misc/src/Main.hx 第 23 行 Sys.exit(result.failures) 把失败数直接映射为退出码,haxe compile.hxml 一次执行即可作为 CI 中的一个检查步骤:退出码为 0 表示全部通过,非 0 表示有失败,同时 stdout 中的 Done running N tests with M failures 与 SUMMARY: 摘要会给出失败工程列表,供日志分析直接定位。这正是 README 所说"在宏测试套件执行期间被逐个执行"的落地形式——测试驱动本身就是一个 Haxe 程序,用编译器自举的方式守护编译器的行为边界。
结语
tests/misc 用一套极简的约定(compile.hxml 成功、compile-fail.hxml 精确匹配 stderr、数字后缀复用目录、MISC_TEST_FILTER 过滤、.disabled 停用)支撑起了 Haxe 编译器数千个回归场景的自动化验证。理解它的组织方式与 Main.hx 的比对细节,既能让你在本地高效复现、验证编译器的历史 Issue,也能为编译器贡献修复时轻松补上配套的回归测试,让缺陷修复真正"可被机器持续守护"。