test(sea): decouple loader tests from the runner's Node version

The unit-test matrix spans Node 14–20, but SeaNativeLoader's version gate
read the live `process.version` before the injected `load` seam ran. On the
14 and 16 runners every "successful load" / "load-failure hints" / "shape
check" test hit `requires Node >=18` instead of the path it asserted (7
failures per job). Make Node-major detection a second injectable ctor seam
(default = live process.version), inject a supported major in the load-path
tests, and inject the version-under-test in the gate's own tests (no more
mutating process.version). Tests now pass identically on every matrix Node.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

lib/sea/SeaNativeLoader.ts

@@ -131,10 +131,20 @@ export class SeaNativeLoader {
 
   private cachedError: Error | undefined;
 
-  constructor(private readonly load: () => SeaNativeBinding = defaultRequire) {}
+  /**
+   * @param load        injectable module-require seam (stub a binding in tests)
+   * @param nodeMajor   injectable Node-major detector. Defaults to reading the
+   *                    live `process.version`; injected in unit tests so the
+   *                    load/shape branches are exercised independently of the
+   *                    runner's actual Node version (the matrix spans 14–20).
+   */
+  constructor(
+    private readonly load: () => SeaNativeBinding = defaultRequire,
+    private readonly nodeMajor: () => number = detectNodeMajor,
+  ) {}
 
   private tryLoad(): SeaNativeBinding | undefined {
-    const nodeMajor = detectNodeMajor();
+    const nodeMajor = this.nodeMajor();
     // Fail closed: if we cannot determine the Node major (NaN) or it is
     // below the floor, refuse the load and fall back to Thrift.
     if (!Number.isFinite(nodeMajor) || nodeMajor < MIN_NODE_MAJOR) {

tests/unit/sea/loader.test.ts

@@ -17,8 +17,13 @@ import { SeaNativeLoader, SeaNativeBinding } from '../../../lib/sea/SeaNativeLoa
 
 // Pure-logic tests for SeaNativeLoader. These exercise the load-failure
 // hint branches, the Node-version gate, the shape check, and caching via
-// the injectable `load` seam — so they run everywhere regardless of
-// whether a real `.node` is installed on the test machine.
+// the injectable `load` and `nodeMajor` seams — so they run everywhere
+// regardless of whether a real `.node` is installed on the test machine
+// OR which Node version the runner happens to be (the CI matrix spans
+// 14–20, below and above the >=18 floor). Tests that exercise the load
+// path inject a supported Node major so the version gate never short-
+// circuits them; the gate's own tests inject the version under test.
+const SUPPORTED_NODE_MAJOR = () => 18;
 
 function stubBinding(overrides: Partial<Record<keyof SeaNativeBinding, unknown>> = {}): SeaNativeBinding {
   return {
@@ -52,7 +57,7 @@ describe('SeaNativeLoader', () => {
   describe('successful load', () => {
     it('get() returns the binding from the injected loader', () => {
       const binding = stubBinding();
-      const loader = new SeaNativeLoader(() => binding);
+      const loader = new SeaNativeLoader(() => binding, SUPPORTED_NODE_MAJOR);
       expect(loader.get()).to.equal(binding);
       expect(loader.tryGet()).to.equal(binding);
     });
@@ -63,7 +68,7 @@ describe('SeaNativeLoader', () => {
       const loader = new SeaNativeLoader(() => {
         calls += 1;
         return binding;
-      });
+      }, SUPPORTED_NODE_MAJOR);
       loader.get();
       loader.tryGet();
       loader.get();
@@ -75,7 +80,7 @@ describe('SeaNativeLoader', () => {
     it('MODULE_NOT_FOUND → "not installed" hint pointing at the README', () => {
       const loader = new SeaNativeLoader(() => {
         throw errWithCode('MODULE_NOT_FOUND', "Cannot find module '../../native/sea'");
-      });
+      }, SUPPORTED_NODE_MAJOR);
       expect(loader.tryGet()).to.equal(undefined);
       const msg = thrownMessage(() => loader.get());
       expect(msg).to.match(/not installed/);
@@ -85,7 +90,7 @@ describe('SeaNativeLoader', () => {
     it('ERR_DLOPEN_FAILED → includes the underlying dlerror string and remediation', () => {
       const loader = new SeaNativeLoader(() => {
         throw errWithCode('ERR_DLOPEN_FAILED', 'GLIBC_2.32 not found');
-      });
+      }, SUPPORTED_NODE_MAJOR);
       const msg = thrownMessage(() => loader.get());
       expect(msg).to.match(/GLIBC_2\.32 not found/);
       expect(msg).to.match(/musl/);
@@ -95,22 +100,22 @@ describe('SeaNativeLoader', () => {
     it('a generic Error (no code) preserves its message', () => {
       const loader = new SeaNativeLoader(() => {
         throw new Error('totally unexpected');
-      });
+      }, SUPPORTED_NODE_MAJOR);
       expect(() => loader.get()).to.throw(/totally unexpected/);
     });
 
     it('a non-Error throw is wrapped', () => {
       const loader = new SeaNativeLoader(() => {
         // eslint-disable-next-line no-throw-literal
         throw 'a string';
-      });
+      }, SUPPORTED_NODE_MAJOR);
       expect(() => loader.get()).to.throw(/non-standard error/);
     });
   });
 
   describe('shape check', () => {
     it('rejects a binding missing an expected export', () => {
-      const loader = new SeaNativeLoader(() => stubBinding({ openSession: undefined }));
+      const loader = new SeaNativeLoader(() => stubBinding({ openSession: undefined }), SUPPORTED_NODE_MAJOR);
       expect(loader.tryGet()).to.equal(undefined);
       const msg = thrownMessage(() => loader.get());
       expect(msg).to.match(/missing expected export/);
@@ -120,30 +125,18 @@ describe('SeaNativeLoader', () => {
 
   describe('Node-version gate', () => {
     it('fails closed on a Node version below the floor', () => {
-      const original = process.version;
-      try {
-        Object.defineProperty(process, 'version', { value: 'v16.20.0', configurable: true });
-        let loadCalled = false;
-        const loader = new SeaNativeLoader(() => {
-          loadCalled = true;
-          return stubBinding();
-        });
-        expect(() => loader.get()).to.throw(/requires Node >=18/);
-        expect(loadCalled, 'load() must not be attempted on an unsupported Node').to.equal(false);
-      } finally {
-        Object.defineProperty(process, 'version', { value: original, configurable: true });
-      }
+      let loadCalled = false;
+      const loader = new SeaNativeLoader(() => {
+        loadCalled = true;
+        return stubBinding();
+      }, () => 16);
+      expect(() => loader.get()).to.throw(/requires Node >=18/);
+      expect(loadCalled, 'load() must not be attempted on an unsupported Node').to.equal(false);
     });
 
     it('fails closed when the Node version is unparseable (NaN)', () => {
-      const original = process.version;
-      try {
-        Object.defineProperty(process, 'version', { value: 'vNOT-A-VERSION', configurable: true });
-        const loader = new SeaNativeLoader(() => stubBinding());
-        expect(() => loader.get()).to.throw(/requires Node >=18/);
-      } finally {
-        Object.defineProperty(process, 'version', { value: original, configurable: true });
-      }
+      const loader = new SeaNativeLoader(() => stubBinding(), () => NaN);
+      expect(() => loader.get()).to.throw(/requires Node >=18/);
     });
   });
 });