test: migrate test suite from jest to the node:test runner

.github/workflows/cross-runtime.yml

@@ -49,6 +49,13 @@ jobs:
         env:
           HUSKY: "0"
 
+      # jest is no longer a project dev-dep (the Node.js test runner is used
+      # instead), so install it ad-hoc just for this job. The bridge shim
+      # (`test/_runner.js`) adapts the suite to jest's globals exactly as it
+      # does on the legacy-test matrix.
+      - name: Install jest
+        run: npm install --no-save --no-package-lock --no-audit jest@^30
+
       - name: Use Deno
         uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4
         with:

.github/workflows/test.yml

@@ -34,6 +34,7 @@ jobs:
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
+      # macOS arm64 runners don't ship Node.js 10/12/14, so force x64.
       - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         id: calculate_architecture
         with:
@@ -50,34 +51,58 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           architecture: ${{ steps.calculate_architecture.outputs.result }}
-          # Legacy Node (10-16) reinstalls deps after dropping/bypassing
-          # package-lock.json, so there's no lockfile for setup-node's npm
-          # cache to key on.
+          # Legacy Node (10-16) reinstalls deps after dropping the lockfile,
+          # so there's nothing for setup-node's npm cache to key on.
           cache: ${{ (matrix.node-version == '10.x' || matrix.node-version == '12.x' || matrix.node-version == '14.x' || matrix.node-version == '16.x') && '' || 'npm' }}
 
-      - name: Install dependencies
+      # TODO: drop the legacy install + jest steps below once `engines.node`
+      # is bumped to >= 18. That also makes `jest.config.js`, the jest branch
+      # of `test/_runner.js`, and `test/polyfill-text-encoding.js` dead code.
+      #
+      # The `node:test` based suite needs Node.js 18+; the library itself
+      # still supports Node.js >= 10.13, so legacy versions run the same test
+      # files under jest via the runner shim (`test/_runner.js`). jest, memfs
+      # and the runtime deps are installed ad-hoc so the modern dev toolchain
+      # (eslint, typescript, prettier) is never required by the legacy leg.
+      - name: Install jest (Node 10)
+        if: matrix.node-version == '10.x'
         shell: bash
         run: |
           rm -f package-lock.json
-
           npm config set progress false
+          yarn add -D jest@^27 memfs@^3 --ignore-scripts --ignore-engines
 
-          if [ "${{ matrix.node-version }}" = "10.x" ]; then
-            yarn add -D typescript@^4 jest@^27 memfs@^3 --ignore-scripts --ignore-engines
-          else
-            npm install -g npm@7
-            npm install -D typescript@^4 jest@^27 memfs@^3 --ignore-scripts --no-audit --prefer-offline --no-save --no-package-lock
-          fi
-        if: matrix.node-version == '10.x' || matrix.node-version == '12.x' || matrix.node-version == '14.x' || matrix.node-version == '16.x'
+      - name: Install jest (Node 12-16)
+        if: matrix.node-version == '12.x' || matrix.node-version == '14.x' || matrix.node-version == '16.x'
+        shell: bash
+        run: |
+          rm -f package-lock.json
+          npm config set progress false
+          npm install -g npm@7
+          npm install -D jest@^27 memfs@^3 --ignore-scripts --no-audit --prefer-offline --no-save --no-package-lock
 
       - name: Install dependencies
-        run: npm ci
         if: matrix.node-version != '10.x' && matrix.node-version != '12.x' && matrix.node-version != '14.x' && matrix.node-version != '16.x'
+        run: npm ci
+
+      - name: Run tests (legacy via jest)
+        if: matrix.node-version == '10.x' || matrix.node-version == '12.x' || matrix.node-version == '14.x' || matrix.node-version == '16.x'
+        run: npx jest --ci
+
+      # The built-in coverage lcov reporter and `--test-coverage-include` are
+      # only available on Node.js 22+, so 18/20 run the suite without
+      # collecting coverage.
+      - name: Run tests
+        if: matrix.node-version == '18.x' || matrix.node-version == '20.x'
+        run: npm run test:only
 
       - name: Run tests with coverage
-        run: npm run test:coverage -- --ci
+        if: matrix.node-version == '22.x' || matrix.node-version == '24.x' || matrix.node-version == '25.x'
+        run: npm run test:coverage
 
       - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        if: matrix.node-version == '22.x' || matrix.node-version == '24.x' || matrix.node-version == '25.x'
         with:
+          files: ./coverage/lcov.info
           flags: integration
           token: ${{ secrets.CODECOV_TOKEN }}

eslint.config.mjs

@@ -24,12 +24,27 @@ export default defineConfig([
 	},
 	{
 		// Cross-runtime smoke scripts run standalone on node/bun/deno and in a
-		// browser sandbox; relax the library-grade JSDoc typing rules for them.
+		// browser sandbox; relax library-grade JSDoc rules, allow console
+		// output (they're CLI scripts) and skip the `engines.node` version
+		// checks (these files target newer runtimes by design).
 		files: ["test/smoke/**/*"],
 		rules: {
 			"jsdoc/no-restricted-syntax": "off",
 			"jsdoc/reject-any-type": "off",
 			"unicorn/prefer-native-coercion-functions": "off",
+			"n/no-unsupported-features/es-builtins": "off",
+			"n/no-unsupported-features/es-syntax": "off",
+			"n/no-unsupported-features/node-builtins": "off",
+			"no-console": "off",
+		},
+	},
+	{
+		// The test suite relies on `node:test` and modern `node:assert` helpers,
+		// which are newer than the `engines.node` range the published library
+		// targets. Tests are dev-only, so the builtin version check does not apply.
+		files: ["test/*.js"],
+		rules: {
+			"n/no-unsupported-features/node-builtins": "off",
 		},
 	},
 ]);

jest.config.js

@@ -1,6 +1,14 @@
 "use strict";
 
+// TODO: drop this file together with `test/_runner.js`'s jest branch and the
+// legacy-only steps in the `test` CI job once `engines.node` is bumped to >= 18.
+
+// Jest config is only consumed by the legacy leg of the test matrix
+// (Node.js < 18) where `node:test` is not available. Modern runs use
+// `node --test` via scripts/test.js and ignore this file.
 module.exports = {
+	roots: ["<rootDir>/test"],
 	moduleFileExtensions: ["js", "mjs", "cjs", "ts"],
+	modulePathIgnorePatterns: ["<rootDir>/test/fixtures/"],
 	setupFiles: ["<rootDir>/test/polyfill-text-encoding.js"],
 };