Hermes 参与 Node-API Conformance Test Suite(node-api-cts)的贡献指南:测试体系、实现者 Harness 与源码级佐证

原创2026-09-23 13:41:211,730 阅读
文章标签:语言运行时解释器JIT编译编译器内存管理嵌入式移动开发

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:

对比二者的 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 是该驱动的核心,其执行流水线如下:

  1. 读取 assert.js 与 load-addon.js 的源码内容;
  2. 解析 hermes-skip-list.txt 跳过列表(按行读取,# 后为注释、空白行忽略、每行一个测试目录名);
  3. 递归收集 tests/js-native-api/*/test.js 并排序;
  4. 对每个测试:若命中跳过列表或对应 .node addon 未构建则计为 SKIP;否则把三段代码拼成一个脚本——先是 var __napiAddonDir = '<ADDON_DIR>';,再依次拼接 assert.js、load-addon.js 与测试本体 test.js;
  5. 写入构建树的临时文件 _hermes_test_runner.js,通过 execute_process 以 QEMU_PREFIX_LIST + hermes + 临时文件 的方式执行(交叉编译时自动加 qemu 前缀),超时上限 120 秒;
  6. 依据退出码判定 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 测试的基本步骤如下:

  1. 准备依赖:确保 external/node-api-cts 下的 node_modules 中存在 node-api-headers(package.json 声明版本 ^1.7.0),因为顶层 CMakeLists.txt 会在 NODE_API_HEADERS_DIR 不存在时直接 FATAL_ERROR;
  2. 配置构建:在 Hermes 的 CMake 配置中启用包含 external/node-api-cts 的选项,使其把 implementors/hermes/CMakeLists.txt 纳入构建,从而生成 cts_2_function_arguments 等 addon 目标与 check-napi-cts 自定义目标;
  3. 构建 addon:编译 cts_2_function_arguments,产出位于构建树中的 2_function_arguments/2_function_arguments.node;
  4. 运行测试:执行 check-napi-cts 目标,CMake 脚本会自动枚举 tests/js-native-api 下的 test.js,拼接 harness 后交给 hermes 二进制执行,并输出 PASS/FAIL/SKIP 统计;交叉编译场景下通过 QEMU_RUN_PREFIX 传入 qemu 前缀即可在目标架构上运行。

六、贡献 Checklist:以 Hermes 实现者视角落地

结合贡献哲学与仓库实际接线,可以从以下几个层面落地你的贡献:

  1. 补测试:在 tests/js-native-api 或 tests/node-api 下按 CTS 的目录约定新增测试目录(含 C/C++ 源码与 test.js),并在 implementors/hermes/CMakeLists.txt 中通过 add_hermes_cts_addon 登记新的 addon、加入 CTS_ADDON_TARGETS 依赖列表;
  2. 改 harness:修改 implementors/hermes/ 下的 assert.js、load-addon.js,或调整 run-cts-tests.cmake 的拼装/执行逻辑;注意保持与 tests/harness 桶的测试兼容;
  3. 维护跳过列表:当某个测试因引擎暂不支持而无法通过时,在 hermes-skip-list.txt 中追加目录名并附上 # 注释说明原因;
  4. 文档与治理:改进本仓库中相关 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 下执行,跳过列表机制则保证了渐进式推进的灵活性。无论你选择修复源码、补充测试、改进文档还是参与工作组,都可以从本仓库的现有实现出发,快速完成第一份贡献。

登录后查看全文
hermes