Skip to content

Commit da7001a

Browse files
kraenhansenclaude
kraenhansen
and
claude
committed
doc: add porting plan with difficulty ratings
Enumerates all 58 test directories from Node.js's test/js-native-api and test/node-api, rates each by porting difficulty (Easy/Medium/Hard), and documents special considerations for tests with deep runtime dependencies (libuv, worker threads, SEA, node_api_post_finalizer, etc.). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 0e2b18b commit da7001a

1 file changed

Lines changed: 164 additions & 0 deletions

File tree

‎PORTING.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Porting Plan
2+
3+
This document tracks the progress of porting tests from Node.js's test suite into the CTS.
4+
The source directories are [`test/js-native-api`](https://github.com/nodejs/node/tree/main/test/js-native-api)
5+
and [`test/node-api`](https://github.com/nodejs/node/tree/main/test/node-api) in the Node.js repository.
6+
7+
Difficulty is assessed on two axes:
8+
- **Size/complexity** — total lines of C/C++ and JS across all source files
9+
- **Runtime-API dependence** — pure `js_native_api.h` is cheapest; Node.js extensions and direct
10+
libuv calls require harness work or Node-only scoping
11+
12+
| Rating | Meaning |
13+
|---|---|
14+
| Easy | Small test, pure `js_native_api.h` or trivial runtime API, straightforward 1:1 port |
15+
| Medium | Moderate size or uses a Node.js extension API that the harness will need to abstract |
16+
| Hard | Large test and/or deep libuv/worker/SEA dependency; may need new harness primitives or Node-only scoping |
17+
18+
## Engine-specific (`js-native-api`)
19+
20+
Tests covering the engine-specific part of Node-API, defined in `js_native_api.h`.
21+
22+
| Directory | Status | Difficulty |
23+
|---|---|---|
24+
| `2_function_arguments` | Ported | — |
25+
| `3_callbacks` | Not ported | Easy |
26+
| `4_object_factory` | Not ported | Easy |
27+
| `5_function_factory` | Not ported | Easy |
28+
| `6_object_wrap` | Not ported | Medium |
29+
| `7_factory_wrap` | Not ported | Easy |
30+
| `8_passing_wrapped` | Not ported | Easy |
31+
| `test_array` | Not ported | Easy |
32+
| `test_bigint` | Not ported | Easy |
33+
| `test_cannot_run_js` | Not ported | Medium |
34+
| `test_constructor` | Not ported | Medium |
35+
| `test_conversions` | Not ported | Medium |
36+
| `test_dataview` | Not ported | Easy |
37+
| `test_date` | Not ported | Easy |
38+
| `test_error` | Not ported | Medium |
39+
| `test_exception` | Not ported | Medium |
40+
| `test_finalizer` | Not ported | Medium |
41+
| `test_function` | Not ported | Medium |
42+
| `test_general` | Not ported | Hard |
43+
| `test_handle_scope` | Not ported | Easy |
44+
| `test_instance_data` | Not ported | Easy |
45+
| `test_new_target` | Not ported | Easy |
46+
| `test_number` | Not ported | Easy |
47+
| `test_object` | Not ported | Hard |
48+
| `test_promise` | Not ported | Easy |
49+
| `test_properties` | Not ported | Easy |
50+
| `test_reference` | Not ported | Medium |
51+
| `test_reference_double_free` | Not ported | Easy |
52+
| `test_sharedarraybuffer` | Not ported | Medium |
53+
| `test_string` | Not ported | Medium |
54+
| `test_symbol` | Not ported | Easy |
55+
| `test_typedarray` | Not ported | Medium |
56+
57+
## Runtime-specific (`node-api`)
58+
59+
Tests covering the runtime-specific part of Node-API, defined in `node_api.h`.
60+
61+
| Directory | Status | Difficulty |
62+
|---|---|---|
63+
| `1_hello_world` | Not ported | Easy |
64+
| `test_async` | Not ported | Hard |
65+
| `test_async_cleanup_hook` | Not ported | Hard |
66+
| `test_async_context` | Not ported | Hard |
67+
| `test_buffer` | Not ported | Medium |
68+
| `test_callback_scope` | Not ported | Hard |
69+
| `test_cleanup_hook` | Not ported | Medium |
70+
| `test_env_teardown_gc` | Not ported | Easy |
71+
| `test_exception` | Not ported | Easy |
72+
| `test_fatal` | Not ported | Hard |
73+
| `test_fatal_exception` | Not ported | Easy |
74+
| `test_general` | Not ported | Medium |
75+
| `test_init_order` | Not ported | Medium |
76+
| `test_instance_data` | Not ported | Hard |
77+
| `test_make_callback` | Not ported | Hard |
78+
| `test_make_callback_recurse` | Not ported | Hard |
79+
| `test_null_init` | Not ported | Medium |
80+
| `test_reference_by_node_api_version` | Not ported | Medium |
81+
| `test_sea_addon` | Not ported | Hard |
82+
| `test_threadsafe_function` | Not ported | Hard |
83+
| `test_threadsafe_function_shutdown` | Not ported | Hard |
84+
| `test_uv_loop` | Not ported | Hard |
85+
| `test_uv_threadpool_size` | Not ported | Hard |
86+
| `test_worker_buffer_callback` | Not ported | Hard |
87+
| `test_worker_terminate` | Not ported | Hard |
88+
| `test_worker_terminate_finalization` | Not ported | Hard |
89+
90+
## Special Considerations
91+
92+
### `node_api_post_finalizer` (`6_object_wrap`, `test_finalizer`)
93+
94+
Both tests call `node_api_post_finalizer` to defer JS-touching work out of the GC finalizer and
95+
onto the main thread. This is a Node.js extension not guaranteed to be present on other engines.
96+
The CTS harness will need a platform-agnostic post-finalizer primitive that implementors can map
97+
to their own deferred-callback mechanism, or the tests need to isolate the post-finalizer cases
98+
into a Node-specific subtest.
99+
100+
### `node_api_set_prototype` / `node_api_get_prototype` (`test_general`, js-native-api)
101+
102+
The general test suite mixes standard `js_native_api.h` assertions with calls to
103+
`node_api_set_prototype` and `node_api_get_prototype`, which are Node.js extensions. These do
104+
not exist on other engines. The CTS port should split the affected test cases into an engine-agnostic
105+
core and a Node-only annex, or guard those cases with a runtime capability check.
106+
107+
### SharedArrayBuffer backing-store creation (`test_sharedarraybuffer`)
108+
109+
While `napi_is_sharedarraybuffer` and `napi_get_typedarray_info` are part of `js_native_api.h`,
110+
the test creates its SharedArrayBuffer via a Node-specific helper. The CTS version will need a
111+
harness-provided factory (something like `create_shared_array_buffer(size)`) that each runtime
112+
can implement using its own path.
113+
114+
### libuv dependency (multiple `node-api` tests)
115+
116+
The following tests call into libuv directly — `napi_get_uv_event_loop`, `uv_thread_t`,
117+
`uv_mutex_t`, `uv_async_t`, `uv_check_t`, `uv_idle_t`, `uv_queue_work`, and related APIs:
118+
119+
- `test_async`, `test_async_cleanup_hook`, `test_async_context`
120+
- `test_callback_scope`
121+
- `test_fatal` (uses `uv_thread_t` to test cross-thread fatal errors)
122+
- `test_instance_data` (async work + threadsafe functions + `uv_thread_t`)
123+
- `test_uv_loop`, `test_uv_threadpool_size`
124+
125+
Porting options:
126+
1. **Node-only scope** — mark these tests as Node.js-only and skip on other runtimes.
127+
2. **Harness abstraction** — introduce a minimal platform-agnostic threading/async API in the
128+
harness (e.g., `cts_thread_create`, `cts_async_schedule`) that implementors back with their
129+
own event loop primitives (libuv, tokio, etc.).
130+
131+
### Threadsafe functions (`test_threadsafe_function`, `test_threadsafe_function_shutdown`)
132+
133+
`test_threadsafe_function` is the largest single test (~700 total lines across C and JS), covering
134+
blocking/non-blocking queue modes, queue-full handling, multiple concurrent threads, finalization
135+
ordering, uncaught exception propagation, and high-precision timing via `uv_hrtime`. The threading
136+
primitives are libuv-specific (same concern as the section above). Porting this test likely depends
137+
on resolving the libuv abstraction question first.
138+
139+
### Worker threads (`test_worker_buffer_callback`, `test_worker_terminate`, `test_worker_terminate_finalization`)
140+
141+
These three tests exercise addon behavior inside Node.js worker threads: buffer finalizer delivery
142+
in worker contexts, function-call behavior under pending exceptions during worker shutdown, and
143+
wrapped-object finalization on forced worker termination. Node.js worker threads have no direct
144+
equivalent in most other Node-API runtimes. These tests are likely Node.js-only and should be
145+
scoped accordingly.
146+
147+
### SEA — Single Executable Applications (`test_sea_addon`)
148+
149+
`test_sea_addon` verifies that a native addon can be loaded inside a Node.js Single Executable
150+
Application. SEA is a Node.js-specific packaging feature with no equivalent in other runtimes.
151+
This test should be excluded from the CTS scope or placed in a Node-only annex.
152+
153+
### `napi_get_node_version` (`test_general`, node-api)
154+
155+
`test_general` calls `napi_get_node_version`, which returns the Node.js major/minor/patch version.
156+
No equivalent exists in other runtimes. The CTS port should either omit that assertion or expose a
157+
harness helper (e.g., `cts_get_runtime_version`) that runtimes can optionally implement.
158+
159+
### Legacy module registration (`test_null_init`)
160+
161+
`test_null_init` exercises the deprecated `NAPI_MODULE` macro with a NULL init function, calling
162+
`napi_module_register` directly. Some newer runtimes that implement Node-API may not support this
163+
legacy registration path. If so, this test should be scoped as Node-only or skipped on runtimes
164+
that only support `NAPI_MODULE_INIT`.

0 commit comments

Comments
 (0)