feat(mocha-to-node-test-runner): migrate mocha@8.x to node:test (v22, v24+) (#313)

Co-authored-by: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com>
Co-authored-by: Bruno Rodrigues <swe@brunocroh.com>
Co-authored-by: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>

Author: 4 people

package-lock.json

@@ -4,7 +4,7 @@
   "description": "Handle DEP0176 via transforming imports of `fs.F_OK`, `fs.R_OK`, `fs.W_OK`, `fs.X_OK` from the root `fs` module to `fs.constants`.",
   "type": "module",
   "scripts": {
-    "test": "npx codemod jssg test -l typescript ./src/workflow.ts ./tests"
+    "test": "npx codemod jssg test --allow-fs -l typescript ./src/workflow.ts ./tests"
   },
   "repository": {
     "type": "git",

recipes/fs-access-mode-constants/package.json

@@ -0,0 +1,165 @@
+# Mocha to Node.js Test Runner
+
+This migrates Mocha 8.x tests to Node.js (22.x, 24.x) test runner
+
+## Features
+
+- Automatically adds `node:test` imports/requires
+- Converts global `describe`, `it`, and hooks to imported versions
+- Transforms `done` callbacks to `(t, done)` signature
+- Converts `this.skip()` to `t.skip()`
+- Converts `this.timeout(N)` to `{ timeout: N }` options
+- Preserves function styles (doesn't convert between `function()` and arrow functions)
+- Supports both CommonJS and ESM
+
+## Examples
+
+### Example 1: Basic
+
+```diff
+ const assert = require('assert');
++const { describe, it } = require('node:test');
+
+ describe('Array', function() {
+   describe.skip('#indexOf()', function() {
+     it('should return -1 when the value is not present', function() {
+       const arr = [1, 2, 3];
+       assert.strictEqual(arr.indexOf(4), -1);
+     });
+   });
+ });
+```
+
+### Example 2: Async
+
+```diff
+ const assert = require('assert');
++const { describe, it } = require('node:test');
+ describe('Async Test', function() {
+-it('should complete after a delay', async function(done) {
++it('should complete after a delay', async function(t, done) {
+   const result = await new Promise(resolve => setTimeout(() => resolve(42), 100));
+   assert.strictEqual(result, 42);
+   });
+ });
+```
+
+### Example 3: Hooks
+
+```diff
+ const assert = require('assert');
+ const fs = require('fs');
++const { describe, before, after, it } = require('node:test');
+ describe('File System', () => {
+   before(function() {
+     fs.writeFileSync('test.txt', 'Hello, World!');
+   });
+
+   after(() => {
+     fs.unlinkSync('test.txt');
+   });
+
+   it('should read the file', () => {
+     const content = fs.readFileSync('test.txt', 'utf8');
+     assert.strictEqual(content, 'Hello, World!');
+   });
+ });
+ ```
+
+### Example 4: Done
+
+```diff
+const assert = require('assert');
++const { describe, it } = require('node:test');
+describe('Callback Test', function() {
+-  it('should call done when complete', function(done) {
++  it('should call done when complete', function(t, done) {
+     setTimeout(() => {
+       assert.strictEqual(1 + 1, 2);
+       done();
+     }, 100);
+   });
+})
+```
+
+### Example 5: Skipped
+
+```diff
+ const assert = require('assert');
++const { describe, it } = require('node:test');
+ describe('Skipped Test', () => {
+   it.skip('should not run this test', () => {
+     assert.strictEqual(1 + 1, 3);
+   });
+-  it('should also be skipped', () => {
+-    this.skip();
++  it('should also be skipped', (t) => {
++    t.skip();
+     assert.strictEqual(1 + 1, 3);
+   });
+
+-  it('should also be skipped 2', (done) => {
+-    this.skip();
++  it('should also be skipped 2', (t, done) => {
++    t.skip();
+     assert.strictEqual(1 + 1, 3);
+   });
+
+-  it('should also be skipped 3', x => {
+-    this.skip();
++  it('should also be skipped 3', (t, x) => {
++    t.skip();
+     assert.strictEqual(1 + 1, 3);
+   });
+ })
+```
+
+### Example 6: Dynamic
+
+```diff
+ const assert = require('assert');
++const { describe, it } = require('node:test');
+ describe('Dynamic Tests', () => {
+   const tests = [1, 2, 3];
+
+   tests.forEach((test) => {
+     it(`should handle test ${test}`, () => {
+       assert.strictEqual(test % 2, 0);
+     });
+   });
+ });
+```
+
+### Example 7: Timeouts
+
+```diff
+const assert = require('assert');
+-describe('Timeout Test', function() {
+-  this.timeout(500);
++const { describe, it } = require('node:test');
++describe('Timeout Test', { timeout: 500 }, function() {
++
++
++  it('should complete within 100ms', { timeout: 100 }, (t, done) => {
+
+-  it('should complete within 100ms', (done) => {
+-    this.timeout(100);
+     setTimeout(done, 500); // This will fail
+   });
+
+-  it('should complete within 200ms', function(done) {
+-    this.timeout(200);
++  it('should complete within 200ms', { timeout: 200 }, function(t, done) {
++
+     setTimeout(done, 100); // This will pass
+   });
+});
+```
+
+## Caveats
+
+* `node:test` doesn't support the `retry` option that Mocha has, so any tests using that will need to be handled separately.
+
+## References
+- [Node Test Runner](https://nodejs.org/api/test.html)
+- [Mocha](https://mochajs.org/)

recipes/mocha-to-node-test-runner/README.md

@@ -0,0 +1,26 @@
+schema_version: "1.0"
+name: "@nodejs/mocha-to-node-test-runner"
+version: 1.0.0
+capabilities:
+  - fs
+  - child_process
+description: Migrate Mocha 8.x tests to Node.js (22.x, 24.x) test runner
+author: Xavier Stouder
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+  - mocha
+  - test
+
+registry:
+  access: public
+  visibility: public

recipes/mocha-to-node-test-runner/codemod.yaml

@@ -0,0 +1,24 @@
+{
+  "name": "@nodejs/mocha-to-node-test-runner",
+  "version": "1.0.0",
+  "description": "Migrate Mocha 8.x tests to Node.js (22.x, 24.x) test runner",
+  "type": "module",
+  "scripts": {
+    "test": "npx codemod jssg test --strictness cst -l typescript ./src/workflow.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodejs/userland-migrations.git",
+    "directory": "recipes/mocha-to-node-test-runner",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "Richie McColl",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/mocha-to-node-test-runner/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.3.1"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*"
+  }
+}

recipes/mocha-to-node-test-runner/package.json

@@ -0,0 +1,13 @@
+import type { Transform } from '@codemod.com/jssg-types/main';
+import type Json from '@codemod.com/jssg-types/langs/json';
+import removeDependencies from '@nodejs/codemod-utils/remove-dependencies';
+
+const transform: Transform<Json> = async (root) => {
+	return removeDependencies(['mocha', '@types/mocha'], {
+		packageJsonPath: root.filename(),
+		runInstall: false,
+		persistFileWrite: false,
+	});
+};
+
+export default transform;