All jobs

Migrate Mocha Tests to the Built-In Node.js Test Runner

Yes. An agent ports Mocha tests to node:test, fixes the callback-style tests that break, removes Mocha, and opens a pull request with the same tests passing.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the tests for the Mocha features they use, since those decide how much work the port is. In a project like h5bp/html5-boilerplate there are two files, test/file_content.mjs and test/file_existence.mjs, both ES modules that import assert from Node and take describe and it from Mocha's globals. There are no hooks and no use of Mocha's this. One test is callback style: it('"style.css" should contain a custom banner', function (done) { ... }) reads the stylesheet through a stream and calls done on close. The other file builds its tests while it loads, calling it once for each file it finds in dist and archive. The script is gulp archive && mocha --reporter spec --timeout 5000 on Mocha 12.0.0, and when this page was written it reported 25 passing.

It ports in small steps and runs the suite after each one, because the failures are instructive. Run unchanged under node --test, both files fail before any test is collected with ReferenceError: describe is not defined. Adding import { describe, it } from 'node:test' to each gives 24 passing and 1 failing. The failure is the callback test: in node:test the first argument of a test function is the test context and the callback is the second, so done receives an object and readStream.on('close', done) throws ERR_INVALID_ARG_TYPE. Changing the signature to function (t, done) gives 25 passing in 4 suites and exit code 0. The agent also notes that the two runners cannot share the files during a transition: once they import from node:test, Mocha loads them, registers nothing and prints 0 passing.

Passing is half of the check. The agent breaks one expectation on purpose to compare how each runner reports it. With one word of the banner altered in dist/css/style.css, Mocha counts the single broken test twice, as Uncaught AssertionError and as done() called multiple times, prints 24 passing and 2 failing, and exits 2. node:test reports 24 passed, 1 failed with AssertionError [ERR_ASSERTION]: true == false, and exits 1. Both fail the build. Anything that parses the count or the exit code would see a difference, and the agent searches the workflows for that.

Then it removes what only Mocha needed. The script becomes gulp archive && node --test --test-reporter=spec --test-timeout=5000; the default discovery already matches test/**/*.mjs. Uninstalling mocha and eslint-plugin-mocha removes 22 packages. The overrides block in package.json pins diff and serialize-javascript, and after the uninstall npm ls finds neither in the tree, so the block goes. eslint.config.mjs imports the Mocha plugin and spreads globals.mocha; with the package gone ESLint cannot load its config, so the agent drops both lines and runs npm run lint again.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate this repository's tests from Mocha to the built-in Node.js test runner. Read package.json, every file in test, eslint.config.mjs and .github/workflows/test.yml first, and list the Mocha features in use: globals, hooks, this, callback-style tests, timeouts, reporters, and tests generated at load time. Run npm ci and npm test and record the count. Port in steps and run the suite after each: first node --test on the unchanged files, then with describe and it imported from node:test, then with whatever each remaining failure needs. Explain each failure from the node:test documentation before fixing it. Keep the build step that the test script runs first. When the count matches, break one assertion on purpose and compare what Mocha and node:test print and their exit codes, then restore it. Map the Mocha flags in the test script to node --test flags, check the lowest Node version in the CI matrix supports each one, remove mocha and any package or config entry that exists only for it, including lint plugins, globals and overrides, and run npm ci, npm test and npm run lint from a clean install. Open a pull request with the output of every command.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that edits the two test files by one import each and one function signature, changes the test script, and removes Mocha from package.json, package-lock.json and eslint.config.mjs. The description shows the suite at each step, 0 collected, then 24 of 25, then 25, with the error that explained each gap. It includes the deliberate failure under both runners and the lint and test output from a clean npm ci.

A reviewer confirms the count matches the old one and that the build still runs first, since every test reads files gulp archive produces. They check the matrix in test.yml: it runs Node 22, 24 and 26 on Ubuntu and Windows, and the runner has been stable since Node 20 while --test-timeout arrived in 20.11, so every cell has the flags used. If anyone on the team relies on Mocha options the script never set, such as --grep or --bail, the description gives the node --test equivalents it found, and says which have none.

Run it on every package that still depends on Mocha

A runner migration is done once per package. For a monorepo or an org with many small libraries, list the packages whose devDependencies include mocha and send this body to POST /o/{org}/sessions once for each repository, with it in resources and a request_id that is a UUID v5 of its name, so a retry of the batch starts nothing twice.

The size of each job follows the Mocha features in use, which is why the prompt asks for that list first. A suite with this.timeout calls, root hooks or a custom reporter takes more edits than this one, and the pull request says where. Runs beyond the key's max_concurrent limit are accepted as queued and start when a slot frees.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The port is a loop of run, read the failure, change one thing, run again, and its value is in the failures being real. The agent has a sandbox with the project's Node version and a clean install, so the 24 of 25 it sees after the first edit is what any contributor would see, and the fix is tied to the error that prompted it. Each iteration's command and output stay with the run.

It also checks the part people skip when a suite goes green: that a broken test still fails, and how. Altering a built file, running both runners, and restoring it is a few commands, but it is the evidence that the new runner catches an assertion thrown inside a stream handler, the one place where the two differ. That comparison comes back in the pull request with both transcripts.

Frequently asked questions

Do I have to rewrite describe and it blocks?

No. node:test exports describe and it with the same shape, so most files need one import line. What changes is the edges: callback tests take the context first and done second, and anything that used this, such as this.timeout(), moves to options or to the test context.

Why did a callback-style test fail after the import?

Because the first parameter means something else. Mocha passes done as the only argument; node:test passes the test context first and the callback second. A function declared as function (done) therefore gets an object, and code that hands it to an event listener throws. Declaring function (t, done) fixes it.

Which Node version do I need for the built-in runner?

The node:test module was added in Node 18 and declared stable in Node 20. The --test-timeout flag needs 20.11 or later. A project whose CI starts at Node 22, like this one, has everything the script uses.

Can Mocha and node:test run the same files during the migration?

Not usefully. After the files import describe and it from node:test, running Mocha on them prints 0 passing, because nothing is registered with Mocha's own globals. Port a directory at a time and point each runner at its own files if the suite is too large to move in one change.

More Mocha jobs

More jobs like this: Hand off a long task

Keep reading