Merge branch 'main' into feat/port-test-finalizer

PORTING.md: keep both new "Ported" rows (test_finalizer from this branch,
test_function from main).

implementors/node/tests.ts: take this branch's spawnTest-based design.

implementors/node/child_process.js: extend HARNESS_MODULE_PATHS with the
skip-test.js and napi-version.js harness modules main introduced.

tests/harness/spawn-test.js: forward --expose-gc to spawnTest children
that should succeed, since main tightened gc.js to refuse loading
without it.

Author: bavulapati

PORTING.md

@@ -57,7 +57,7 @@ Tests covering the engine-specific part of Node-API, defined in `js_native_api.h
 | `test_error`                 | Ported ✅  | Medium     |
 | `test_exception`             | Not ported | Medium     |
 | `test_finalizer`             | Ported ✅  | Medium     |
-| `test_function`              | Not ported | Medium     |
+| `test_function`              | Ported ✅  | Medium     |
 | `test_general`               | Not ported | Hard       |
 | `test_handle_scope`          | Ported ✅  | Easy       |
 | `test_instance_data`         | Not ported | Medium     |

eslint.config.js

@@ -21,6 +21,7 @@ export default defineConfig([
         loadAddon: "readonly",
         mustCall: "readonly",
         mustNotCall: "readonly",
+        gc: "readonly",
         gcUntil: "readonly",
         spawnTest: "readonly",
         experimentalFeatures: "readonly",

implementors/node/README.md

@@ -0,0 +1,27 @@
+# Harness of Node.js
+
+## Build addons
+
+To build the addons, run the following command:
+
+```bash
+$ npm run addons:configure
+$ npm run addons:build
+```
+
+## Running tests
+
+Run the following command to run the tests:
+
+```bash
+$ npm run node:test
+```
+
+To run a specific test file, use the `--test-name-pattern` flag:
+
+```bash
+$ NODE_OPTIONS=--test-name-pattern=js-native-api/test_constructor/test_null npm run node:test
+```
+
+The test names are their relative path to the `tests` folder, with file extensions.
+The pattern can be a regular expression.

implementors/node/child_process.js

@@ -7,6 +7,8 @@ const HARNESS_MODULE_PATHS = [
   "load-addon.js",
   "gc.js",
   "must-call.js",
+  "skip-test.js",
+  "napi-version.js",
   "child_process.js",
 ].map((file) => path.join(import.meta.dirname, file));
 

implementors/node/features.js

@@ -7,9 +7,3 @@ globalThis.experimentalFeatures = {
   setPrototype: true,
   postFinalizer: true,
 };
-
-globalThis.napiVersion = Number(process.versions.napi);
-
-globalThis.skipTest = () => {
-  process.exit(0);
-};

implementors/node/gc.js

@@ -1,13 +1,26 @@
+// Capture the engine-provided gc (Node exposes it under --expose-gc) before
+// we overwrite globalThis.gc with the harness wrapper below.
+const engineGc = globalThis.gc;
+if (typeof engineGc !== "function") {
+  throw new Error(
+    "Node harness expects globalThis.gc to be available (run with --expose-gc)",
+  );
+}
+
+const gc = () => {
+  engineGc();
+};
+
 const gcUntil = async (name, condition) => {
   let count = 0;
   while (!condition()) {
     await new Promise((resolve) => setImmediate(resolve));
     if (++count < 10) {
-      globalThis.gc();
+      engineGc();
     } else {
       throw new Error(`GC test "${name}" failed after ${count} attempts`);
     }
   }
 };
 
-Object.assign(globalThis, { gcUntil });
+Object.assign(globalThis, { gc, gcUntil });

implementors/node/napi-version.js

@@ -0,0 +1 @@
+globalThis.napiVersion = Number(process.versions.napi);

implementors/node/run-tests.ts

@@ -1,36 +1,25 @@
 import path from "node:path";
-import { test, type TestContext } from "node:test";
+import { test } from "node:test";
 
 import { listDirectoryEntries, runFileInSubprocess } from "./tests.ts";
 
 const ROOT_PATH = path.resolve(import.meta.dirname, "..", "..");
 const TESTS_ROOT_PATH = path.join(ROOT_PATH, "tests");
 
-async function populateSuite(
-  testContext: TestContext,
+function populateSuite(
   dir: string
-): Promise<void> {
+) {
   const { directories, files } = listDirectoryEntries(dir);
 
   for (const file of files) {
-    await testContext.test(file, () => runFileInSubprocess(dir, file));
+    test(path.relative(TESTS_ROOT_PATH, path.join(dir, file)), () => runFileInSubprocess(dir, file));
   }
 
   for (const directory of directories) {
-    await testContext.test(directory, async (subTest) => {
-      await populateSuite(subTest, path.join(dir, directory));
-    });
+    populateSuite(path.join(dir, directory));
   }
 }
 
-test("harness", async (t) => {
-  await populateSuite(t, path.join(TESTS_ROOT_PATH, "harness"));
-});
-
-test("js-native-api", async (t) => {
-  await populateSuite(t, path.join(TESTS_ROOT_PATH, "js-native-api"));
-});
-
-test("node-api", async (t) => {
-  await populateSuite(t, path.join(TESTS_ROOT_PATH, "node-api"));
-});
+populateSuite(path.join(TESTS_ROOT_PATH, "harness"));
+populateSuite(path.join(TESTS_ROOT_PATH, "js-native-api"));
+populateSuite(path.join(TESTS_ROOT_PATH, "node-api"));

implementors/node/skip-test.js

@@ -0,0 +1,3 @@
+globalThis.skipTest = () => {
+  process.exit(0);
+};

tests/harness/gc.js

@@ -1,7 +1,14 @@
+if (typeof gc !== 'function') {
+  throw new Error('Expected a global gc function');
+}
+
 if (typeof gcUntil !== 'function') {
   throw new Error('Expected a global gcUntil function');
 }
 
+// gc should run synchronously without throwing
+gc();
+
 // gcUntil should resolve once the condition becomes true
 let count = 0;
 await gcUntil('test-passes', () => {