Rolldown esbuild 兼容性测试:glob 特性支持现状与用例全解析
Rolldown esbuild 兼容性测试:glob 特性支持现状与用例全解析
本篇文章围绕 Rolldown 仓库中 esbuild 兼容性测试的 glob 特性汇总文档(scripts/src/esbuild-tests/snap-diff/summary/glob.md),解读该文档的四段式结构、glob 分类下各测试用例的通过/未支持状态,并结合统计报表、测试夹具与生成脚本,讲清这套"快照差异(snap-diff)"兼容性追踪体系的工作方式。读完本文,你将能够读懂并复现任一 glob 用例,理解 ignored (not supported) 与 failed 的区分逻辑,并掌握向该套件新增/扩展兼容性用例的入口。
一、这份汇总文档是什么:esbuild 兼容性追踪体系的"分类日报"
Rolldown 以 Rollup 兼容 API 为目标的 Rust bundler,为了量化与 esbuild 的行为差异,仓库内置了一套"从 esbuild 官方测试套件生成用例 → 运行 Rolldown → 与 esbuild 快照对比 → 输出分类汇总"的流水线。其最终产物之一是 snap-diff 目录下的多份分类摘要:
- summary/glob.md —— 本文主角,glob 特性分类
- summary/default.md、summary/ts.md、summary/loader.md 等同级文件 —— 其他特性分类
- stats/stats.md —— 全部分类的汇总指标
每份 summary 文档固定按四个段落组织:Failed Cases(失败)、Passed Cases(通过)、Ignored Cases(忽略)、Ignored Cases (not supported)(不支持而忽略)。glob 分类的当前结论非常清晰:
- Failed Cases:0 个
- Passed Cases:1 个 ——
glob_basic_no_bundle - Ignored Cases:0 个
- Ignored Cases (not supported):8 个,原因统一标注为
glob is not supported
也就是说,glob 分类下 9 个用例中,除 1 个通过外,其余 8 个均因"glob 暂不支持"被归入忽略队列。这与 reasons.ts 中的 notSupportedReasons 记录一一对应(第 105–112 行恰好列出这 8 个用例,原因均为 'glob is not supported')。
二、数据全景:glob 在整体兼容性指标中的位置
stats/stats.md 给出了全部 10 个分类的兼容性指标,其中 glob 分类的数据如下:
## glob
- total: 9
- ignored: 8
- passed: 1
- passed ratio: 100.00%
解读这套指标需要理解它的计算口径:passed ratio 是按"已执行用例"(total − ignored)为分母计算的,因此 1 / (9 − 8) = 100%。这解释了为什么 glob 分类显示 100%——不是所有 glob 用例都通过,而是未被忽略的用例全部通过。这与 stats.md 开头"Compatibility metric without not supported case"(总通过率 96.63%)的统计口径一致:忽略项不计入通过率分母。
从全局看,stats.md 记录的总体数据为:total 824、ignored 112、passed 688、通过率 87.42%;剔除 not supported 后为 96.63%。glob 是其中被忽略比例最高的分类之一(8/9),其余分类如 importstar、importstar_ts、lower、splitting 均已 100% 通过。
三、通过用例详解:glob_basic_no_bundle
glob_basic_no_bundle 是 glob 分类中唯一进入 Passed 段的用例,其夹具位于 crates/rolldown/tests/esbuild/glob/glob_basic_no_bundle,由三部分构成。
1. 配置 _config.json
_config.json 展示了该套件测试配置的典型字段:
{
"config": {
"input": [
{
"name": "entry",
"import": "entry.js"
}
],
"format": "cjs",
"treeshake": false
},
"expectExecuted": false
}
input:入口列表,name为逻辑入口名,import为相对路径;format: "cjs":输出格式,其他用例中可见esm等取值;treeshake: false:关闭 tree-shaking(no_bundle场景下保持原样输出);expectExecuted: false:不要求产物可实际运行,仅做产物快照对比。
2. 入口源码 entry.js
entry.js 的核心内容是一段运行时才能确定路径的动态加载代码:
const ab = Math.random() < 0.5 ? 'a.js' : 'b.js'
console.log({
concat: {
require: require('./src/' + ab),
import: import('./src/' + ab),
},
template: {
require: require(`./src/${ab}`),
import: import(`./src/${ab}`),
},
})
可以看到它覆盖了两个维度:require / import 两种加载方式,以及字符串拼接('./src/' + ab)与模板字符串(`./src/${ab}`)两种动态路径写法。从夹具内容可以推断,glob 分类下的测试统一考察"带运行时变量的路径表达式在打包时如何处理"这一主题。
3. 产物快照 artifacts.snap
artifacts.snap 记录了 Rolldown 的实际输出,文件头标注 source: crates/rolldown_testing/src/integration_test.rs,说明该快照由 crates/rolldown_testing/src/integration_test.rs 驱动生成。在 no_bundle 模式下,动态加载语句被原样保留、仅做格式化:
//#region entry.js
const ab = Math.random() < .5 ? "a.js" : "b.js";
console.log({
concat: {
require: require("./src/" + ab),
import: import("./src/" + ab)
},
// ...
});
//#endregion
由于本用例未执行打包(动态路径无法静态解析),产物与 esbuild 基线一致,因此被判定为通过。
四、未支持用例逐一解读:glob 的 8 个 ignored (not supported)
glob 分类的另外 8 个用例全部以 glob is not supported 的原因被忽略。它们分布在 crates/rolldown/tests/esbuild/glob 目录下,可从维度上归纳为四组:
| 用例 | 覆盖维度 | 夹具要点 |
|---|---|---|
glob_basic_no_splitting |
打包、无代码分割 | format: "cjs",动态 require/import 拼接路径 |
glob_basic_splitting |
打包、代码分割 | 配置与 no_splitting 相同,开启 splitting 语义 |
ts_glob_basic_no_splitting |
TypeScript 入口 | 入口为 entry.ts,动态加载 './src/' + ab(a.ts / b.ts) |
ts_glob_basic_splitting |
TS 入口 + 代码分割 | 同上,叠加 splitting |
glob_wildcard_no_slash |
通配符、不跨目录 | 动态路径为 './src/file-' + ab + '.js',* 不匹配 / |
glob_wildcard_slash |
通配符、跨目录 | 动态路径同样形如 file-<var>.js,** 语义涉及目录层级 |
glob_no_matches |
零匹配场景 | 动态加载 './src/' + ab + '.json',src/dummy.js 提供目录存在性 |
glob_entry_point_abs_path |
绝对路径入口 | 考察绝对路径形式的 glob 入口处理 |
以 glob_no_matches/entry.js 为例,它把动态路径扩展到了 JSON 扩展名:
const ab = Math.random() < 0.5 ? 'a.js' : 'b.js'
console.log({
concat: {
require: require('./src/' + ab + '.json'),
import: import('./src/' + ab + '.json'),
},
template: {
require: require(`./src/${ab}.json`),
import: import(`./src/${ab}.json`),
},
})
从这些夹具分布看,esbuild 侧对 glob 场景的考察覆盖了打包/不打包、代码分割、TS 入口、通配符跨目录、零匹配、绝对路径等多重组合,而 Rolldown 当前尚未实现对应行为,因此统一以 "glob is not supported" 归入忽略,而非失败——这一归类策略保证了通过率指标不被"已知未实现"的用例污染。
五、状态分类机制:reasons.ts 中 failed / not supported / ignored 的区分
reasons.ts 是理解整个汇总体系的关键文件,它维护了三张"原因表":
failedReasons:命中此表的用例在 summary 中标记为 Failed。例如dce/tree_shaking_unary_operators(关联 oxc 问题)、default/false_require(require出现在参数位置时应改名)等,每条都附具体原因或 issue 链接;notSupportedReasons:命中此表的用例标记为 Ignored Cases (not supported)。除 8 个 glob 用例外,还包括 copy loader、import attributes、mangle props(oxc minifier 不支持)、legal comments 的多种模式、publicPath等价选项等一长串明确未实现能力;ignoreReasons:命中此表的用例标记为 Ignored Cases,原因多为测试基建限制(如 CI 难以稳定的绝对路径用例)、与 Rolldown 设计取向不同(如inject行为对齐@rollup/plugin-inject)、或明确"不会支持"的选项(如lineLimit)。
这套"先归因、再汇总"的机制意味着:summary 文档中的每一行 Ignored 都对应一个可追溯的技术理由,而非简单的跳过。比如 glob 的 8 行 glob is not supported,正是 reasons.ts 第 105–112 行 notSupportedReasons 的直接输出。未来若 Rolldown 实现 glob 支持,只需删除这些条目并重新生成快照,相关用例便会转入 Failed/Passed 统计。
六、用例如何产生与对比:gen-tests.ts 与 snap-diff 流水线
这套兼容性数据并非手写维护,而是从 esbuild 的 Go 测试源码自动生成。入口脚本为 gen-tests.ts,其文件头注释给出了用法:
// To use this script, run:
// pnpm run gen-esbuild-tests <test-suite-name>
脚本内部定义了各测试套件与 esbuild Go 源文件的映射(suites 对象),例如 default 对应 bundler_default_test.go、ts 对应 bundler_ts_test.go 等,并使用 tree-sitter 解析 Go 测试代码,从中抽取入口文件、配置与期望,落盘为 crates/rolldown/tests/esbuild/<category>/<case>/ 下的夹具目录。
对比与汇总阶段由 snap-diff 目录下的脚本完成:
- diff.ts:执行 Rolldown 并对比产物快照;
- runner.ts、snap-parser.ts:解析 esbuild 官方快照与 Rolldown 快照;
- download-snapshots.ts:拉取 esbuild 基线快照;
- index.ts、rewrite.ts:聚合结果并重写 summary/stats 文档。
因此,summary/glob.md 实际是流水线自动生成的"输出产物",任何 glob 用例的状态变化都会反映到该文件,再汇总进 stats.md 的兼容性指标。
七、对开发者的实战指引
复现某个 glob 用例
以 glob_basic_no_splitting 为例,直接进入其夹具目录即可看到完整输入:
crates/rolldown/tests/esbuild/glob/glob_basic_no_splitting/
├── _config.json # 打包配置(format: cjs)
├── artifacts.snap # Rolldown 产物快照(当前为"未支持"占位)
├── entry.js # 入口源码
└── src/
├── a.js
└── b.js # 动态路径可能命中的文件
在 crates/rolldown/tests/esbuild/glob/glob_basic_splitting/src/ 下还同时存在 a.js、b.js 与对应 .map 文件,用于验证动态路径命中后打包/分割的正确性。
判断一个用例属于哪类状态
阅读 summary 时按以下规则对照 reasons.ts:
- 出现在
Passed Cases:产物与 esbuild 基线一致; - 出现在
Failed Cases:已执行但产物不一致,原因是failedReasons中记录的具体缺陷(多为 sub optimal 或依赖 oxc 的已知问题); - 出现在
Ignored Cases:因测试基建或设计取向差异被忽略(ignoreReasons); - 出现在
Ignored Cases (not supported):功能未实现(notSupportedReasons),glob 的 8 个用例全部属于此类。
扩展这套兼容性测试
若想新增一个 glob 相关用例,标准路径是:修改/补充 esbuild 上游测试源后,运行 pnpm run gen-esbuild-tests <suite> 重新生成夹具;若想调整现有用例的状态归类,则编辑 reasons.ts 中的三张表并重新运行 snap-diff 流程,最终产物会自动更新 summary/glob.md 与 stats/stats.md。
结语
summary/glob.md 虽然只有短短 21 行,却是 Rolldown esbuild 兼容性工程化的一个缩影:它以机器可读的固定格式,精确记录了一类特性(glob)的通过/失败/忽略状态,并与 reasons.ts 的归因表、gen-tests.ts 的生成链路、stats.md 的量化指标构成闭环。读懂这份文档,就掌握了进入 Rolldown 兼容性测试体系的一把钥匙。