Support experimental Node-API features in the CTS

[kraenhansen]

Problem

Some Node-API tests in the upstream Node.js repository use experimental APIs guarded behind #ifdef NAPI_EXPERIMENTAL in Node.js's js_native_api.h. The node-api-headers package (which the CTS uses for compilation) does not include any of these experimental API declarations — it only ships stable APIs up to NAPI_VERSION 8.

The following experimental APIs are in Node.js's headers but absent from node-api-headers:

Feature macro	APIs
NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER	node_api_is_sharedarraybuffer, node_api_create_sharedarraybuffer
NODE_API_EXPERIMENTAL_HAS_CREATE_OBJECT_WITH_PROPERTIES	node_api_create_object_with_properties
NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE	node_api_set_prototype
NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER	node_api_post_finalizer

When porting tests that use these APIs, we currently have to strip out the experimental test cases entirely, meaning the CTS can't validate experimental feature support.

Affected tests

Among js-native-api tests:

• test_dataview — uses node_api_is_sharedarraybuffer (currently ported with SAB tests removed)
• test_sharedarraybuffer — uses node_api_is_sharedarraybuffer, node_api_create_sharedarraybuffer
• test_object — uses node_api_create_object_with_properties
• test_general — uses node_api_set_prototype, node_api_post_finalizer
• test_finalizer — uses node_api_post_finalizer
• 6_object_wrap (one build target) — uses node_api_post_finalizer

Suggested approach

1. CTS experimental API header

Create tests/js-native-api/experimental_apis.h with forward declarations for experimental APIs. Each group guarded by its feature macro (matching the Node.js convention):

#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
NAPI_EXTERN napi_status NAPI_CDECL
node_api_is_sharedarraybuffer(napi_env env, napi_value value, bool* result);
// ...
#endif

If/when node-api-headers is updated to include these declarations, the CTS header can be removed.

2. CMake helper for experimental addons

Add add_node_api_cts_experimental_addon() that compiles with NAPI_VERSION=2147483647 (so the addon registers as experimental with the runtime) and defines the requested feature macros.

3. Implementor feature declaration

Each implementor provides a features.js that declares which experimental features the runtime supports (e.g., globalThis.experimentalFeatures = { sharedarraybuffer: true }), injected alongside other harness globals.

4. Conditional test execution

JS tests wrap experimental assertions in if (experimentalFeatures.<feature>) { ... } guards, so they skip gracefully when a runtime doesn't support the feature.

Key detail: NAPI_VERSION and addon registration

When NAPI_EXPERIMENTAL is defined in Node.js's headers, NAPI_VERSION is set to NAPI_VERSION_EXPERIMENTAL (2147483647). The NAPI_MODULE macro exports this version, and the runtime reads it to decide whether to enable experimental behavior for that addon. The CTS needs to replicate this by explicitly setting NAPI_VERSION=2147483647 for experimental addons.