Hermes 参与 Node-API Conformance Test Suite(node-api-cts)的贡献指南:测试体系、实现者 Harness 与源码级佐证
Hermes 参与 Node-API Conformance Test Suite(node-api-cts)的贡献指南:测试体系、实现者 Harness 与源码级佐证
Node-API Conformance Test Suite(node-api-cts)是一套面向不同 JS 引擎与运行时的 Node-API 一致性测试套件,本指南以仓库中 external/node-api-cts/CONTRIBUTING.md 的贡献理念为骨架,结合该子仓库的测试布局、实现者 Harness 以及 Hermes 仓库中的实际接入代码,说明"如何为 node-api-cts 做贡献、如何理解其运行机制、Hermes 是如何参与其中的"。读完本文,你将掌握该测试套件的目录结构、实现者自定义 Harness 的接入方式,以及 Hermes 在构建与运行时层面的具体执行链路,能够直接基于本仓库开展贡献与验证工作。
一、node-api-cts 的贡献理念:多种方式,欢迎参与
node-api-cts 由维护 node-addon-api 的团队负责维护,其贡献哲学非常开放,官方在 external/node-api-cts/CONTRIBUTING.md 中明确列出了四条主要贡献途径:
- 源码修复(Source code fixes):修复测试套件本身、Harness 或相关工具链中的缺陷;
- 补充测试(Additional tests):为 Node-API 的引擎相关(
js_native_api.h)或运行时相关(node_api.h)功能新增测试用例; - 文档改进(Documentation improvements):完善 README、贡献说明等文档;
- 加入 Node-API 工作组并参与会议(Joining the Node-API working group and participating in meetings):从社区治理层面推动 Node-API 生态的演进。
需要注意,node-api-cts 在 README 中声明当前仍处于 work-in-progress(WIP) 状态,不应被任何人在生产环境中完全依赖,因此贡献时应以实验性、演进中的心态对待。
二、测试套件整体结构:三大测试桶与两类 Node-API 头文件
在动手贡献之前,需要先理解测试套件的目录划分。根据 README 与 package.json 的说明,测试被分为三个"桶"(bucket):
| 测试桶 | 位置 | 覆盖对象 |
|---|---|---|
| Harness 测试 | tests/harness/* |
锻炼实现者(implementor)自定义测试 Harness 本身是否工作正常 |
| js-native-api 测试 | tests/js-native-api/* |
基于 js_native_api.h 声明的、引擎相关(engine-specific)的 Node-API 函数 |
| node-api 测试 | tests/node-api/* |
基于 node_api.h 声明的、运行时相关(runtime-specific)的 Node-API 函数 |
其中,js_native_api.h 与 node_api.h 两个头文件分别来自 node-api-headers 包(package.json 的 devDependencies 中声明了 node-api-headers: ^1.7.0)。前者描述与具体 JS 引擎强相关的底层 API,后者则描述与运行时(如事件循环、模块加载)相关的上层 API,二者共同构成完整的 Node-API 契约。
从 CMakeLists.txt 可以看出测试加装的编译方式:CMake 通过 file(GLOB_RECURSE cmake_dirs ... tests/*/CMakeLists.txt) 递归收集 tests/ 下所有子目录中的 CMakeLists.txt,并逐个 add_subdirectory;add_node_api_cts_addon 函数把测试源码编译为共享库,产出无前缀、后缀为 .node 的二进制(PREFIX ""、SUFFIX ".node"),并要求 cxx_std_17;在 Apple 平台追加 -undefined dynamic_lookup 链接标志,使 addon 能在加载时从宿主进程解析 NAPI 符号。
三、实现者(Implementor)Harness:把测试套件"搬进"你自己的引擎
node-api-cts 的一个关键设计是:实现者可以在本仓库的 implementors/ 子目录下维护自己引擎专属的 Harness。这样做的目的是提升迭代速度、促进各 Harness 之间的代码复用。README 中写道:"This repository offers an opportunity for implementors of Node-API to maintain (parts of) their implementor-specific harness inside this repository, in a sub-directory of the implementors directory."
当前仓库中已存在两个实现者的 Harness:
- external/node-api-cts/implementors/hermes/:Hermes(本仓库)的接入实现,由 Meta 维护;
- external/node-api-cts/implementors/node/:Node.js 官方的接入实现。
对比二者的 assert.js 与 load-addon.js,可以直观看到 Harness 的职责——为每个测试注入 assert 全局函数与 loadAddon() 加载函数:
Node 实现者(assert.js、load-addon.js):
assert委托给node:assert/strict的ok;loadAddon校验参数必须是字符串且不带.node后缀,然后基于process.cwd()拼接路径、检查文件存在,最后通过process.dlopen(constants.dlopen.RTLD_NOW)动态加载 addon 并返回其 exports;- 运行入口是 run-tests.ts,使用 Node 内置的
node:test递归遍历tests/harness、tests/js-native-api、tests/node-api三个目录,对每个文件通过 tests.ts 的子进程机制执行;package.json 中的node:test脚本为node --test ./implementors/node/run-tests.ts。
Hermes 实现者(assert.js、load-addon.js):
assert是自实现的轻量函数,值为假时抛出带消息的Error;loadAddon(addonName)期望__napiAddonDir已作为全局变量被注入,拼接__napiAddonDir + '/' + addonName + '.node'后调用 Hermes 提供的原生加载接口loadNativeModule(path)返回模块导出。
可见,同一份 CTS 测试代码,通过不同实现者的 loadAddon,可以分别在 Node 的 dlopen 与 Hermes 的 loadNativeModule 上运行,这正是"跨引擎一致性测试"的核心。
四、Hermes 如何参与:构建期 CTS Addon 与运行期测试驱动
Hermes 的接入并不是把 implementors/hermes 下的文件直接丢给上游,而是通过 CMake 与一个独立的 CMake 脚本,将 CTS 测试编译为 Hermes 的 NAPI addon 并在 Hermes CLI 下执行。这构成了"源码级证据"最密集的部分。
4.1 构建期:add_hermes_cts_addon
implementors/hermes/CMakeLists.txt 定义了 add_hermes_cts_addon(ADDON_NAME SRC) 函数,其关键动作如下:
- 源码目录取自
tests/js-native-api/${ADDON_NAME}(例如2_function_arguments目录下的2_function_arguments.c); - 产出物输出到 构建树(
${CMAKE_CURRENT_BINARY_DIR}/${ADDON_NAME}),而非源树,避免污染源目录; - 头文件搜索路径包含三处:
${PROJECT_SOURCE_DIR}/include(Hermes 的公开头文件)、${CTS_TESTS_DIR}(CTS 提供的common.h/entry_point.h)、${PROJECT_SOURCE_DIR}/include/hermes/napi(提供<js_native_api.h>与<node_api.h>); - 编译特性要求
cxx_std_17,并通过ADDON_NAME=${ADDON_NAME}编译宏向entry_point.h中的NAPI_MODULE宏传递模块名; - Apple 平台同样追加
-undefined dynamic_lookup链接标志。
当前实现只接入了一个示例 addon:add_hermes_cts_addon(2_function_arguments 2_function_arguments.c),并登记到 CTS_ADDON_TARGETS 变量中参与依赖追踪。
4.2 运行期:check-napi-cts 自定义目标与 run-cts-tests.cmake
构建完 addon 后,check-napi-cts 自定义目标负责把所有测试跑起来。它依赖 hermes 二进制与所有 CTS addon 目标,并调用 cmake -P run-cts-tests.cmake 传入五个变量:
HERMES:hermes 可执行文件的完整路径($<TARGET_FILE:hermes>);CTS_TESTS_DIR:tests/js-native-api目录;IMPLEMENTOR_DIR:implementors/hermes目录;ADDON_BASE_DIR:构建树中存放.node文件的根目录;QEMU_RUN_PREFIX:交叉编译时的运行前缀(例如qemu-arm -L /path/to/sysroot),原生构建时为空。
run-cts-tests.cmake 是该驱动的核心,其执行流水线如下:
- 读取
assert.js与load-addon.js的源码内容; - 解析 hermes-skip-list.txt 跳过列表(按行读取,
#后为注释、空白行忽略、每行一个测试目录名); - 递归收集
tests/js-native-api/*/test.js并排序; - 对每个测试:若命中跳过列表或对应
.nodeaddon 未构建则计为 SKIP;否则把三段代码拼成一个脚本——先是var __napiAddonDir = '<ADDON_DIR>';,再依次拼接assert.js、load-addon.js与测试本体test.js; - 写入构建树的临时文件
_hermes_test_runner.js,通过execute_process以QEMU_PREFIX_LIST + hermes + 临时文件的方式执行(交叉编译时自动加 qemu 前缀),超时上限 120 秒; - 依据退出码判定 PASS/FAIL,最后输出
Total / Pass / Fail / Skip汇总,只要有失败就以FATAL_ERROR结束,让上层构建系统感知失败。
值得一提的是,当前 hermes-skip-list.txt 的注释明确写着 "Currently all CTS tests pass — no entries needed",即当前 Hermes 上所有已接入的 CTS 测试全部通过,无需任何跳过项。
4.3 与 Hermes NAPI 实现的衔接
Hermes 的 NAPI 实现位于 API/napi/ 目录,头文件暴露在 include/hermes/napi/ 下,CMake 中的 target_include_directories 正是让 CTS addon 直接包含这些声明。loadNativeModule 则对应 Hermes 提供的原生模块加载能力,是 load-addon.js 得以在 Hermes 内部动态加载 .node 二进制的底层支撑。也就是说,CTS 测试编译产物之所以能在 Hermes 中运行,依赖的是 Hermes NAPI 层对 js_native_api.h / node_api.h 声明的完整实现,以及 Hermes 自身的模块加载机制。
五、如何在本地构建并运行 Hermes 的 CTS 测试
根据上述 CMake 接线,在 Hermes 仓库中启用并运行 Node-API CTS 测试的基本步骤如下:
- 准备依赖:确保
external/node-api-cts下的node_modules中存在node-api-headers(package.json声明版本^1.7.0),因为顶层 CMakeLists.txt 会在NODE_API_HEADERS_DIR不存在时直接FATAL_ERROR; - 配置构建:在 Hermes 的 CMake 配置中启用包含
external/node-api-cts的选项,使其把implementors/hermes/CMakeLists.txt纳入构建,从而生成cts_2_function_arguments等 addon 目标与check-napi-cts自定义目标; - 构建 addon:编译
cts_2_function_arguments,产出位于构建树中的2_function_arguments/2_function_arguments.node; - 运行测试:执行
check-napi-cts目标,CMake 脚本会自动枚举tests/js-native-api下的test.js,拼接 harness 后交给hermes二进制执行,并输出 PASS/FAIL/SKIP 统计;交叉编译场景下通过QEMU_RUN_PREFIX传入 qemu 前缀即可在目标架构上运行。
六、贡献 Checklist:以 Hermes 实现者视角落地
结合贡献哲学与仓库实际接线,可以从以下几个层面落地你的贡献:
- 补测试:在
tests/js-native-api或tests/node-api下按 CTS 的目录约定新增测试目录(含 C/C++ 源码与test.js),并在implementors/hermes/CMakeLists.txt中通过add_hermes_cts_addon登记新的 addon、加入CTS_ADDON_TARGETS依赖列表; - 改 harness:修改
implementors/hermes/下的assert.js、load-addon.js,或调整run-cts-tests.cmake的拼装/执行逻辑;注意保持与tests/harness桶的测试兼容; - 维护跳过列表:当某个测试因引擎暂不支持而无法通过时,在 hermes-skip-list.txt 中追加目录名并附上
#注释说明原因; - 文档与治理:改进本仓库中相关 README/文档,或参与 Node-API working group 会议推动测试契约的演进。
需要提醒的是,该测试套件仍处于 WIP 阶段(见 README 的 IMPORTANT 提示),任何基于它的结论都应保持谨慎,并以仓库当前源码与测试结果为准。
七、小结
node-api-cts 通过"统一测试代码 + 实现者自定义 Harness"的架构,让 Node-API 在 Node.js、Hermes 等多个引擎间保持行为一致。Hermes 在仓库中的接入以 implementors/hermes/ 为承载:构建期由 CMake 把 CTS 测试编译成 Hermes NAPI addon,运行期由 run-cts-tests.cmake 拼接 harness 并在 hermes CLI 下执行,跳过列表机制则保证了渐进式推进的灵活性。无论你选择修复源码、补充测试、改进文档还是参与工作组,都可以从本仓库的现有实现出发,快速完成第一份贡献。