# 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 Rush](https://cloud.getrush.ai/run/migrate-mocha-to-node-test/mocha/). Opens 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`

```json
{
  "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.

## 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

- [Migrate a Node.js Library from Mocha to Vitest](https://getrush.ai/run/migrate-mocha-to-vitest/mocha/)
- [Add Coverage Thresholds to a Mocha Suite With nyc](https://getrush.ai/run/add-coverage-thresholds/mocha/)
- [Run a Mocha Suite in Parallel With --parallel](https://getrush.ai/run/add-parallel-tests/mocha/)

## More jobs like this: Hand off a long task

- [Migrate a Fastify API From MySQL to PostgreSQL](https://getrush.ai/run/migrate-mysql-to-postgres/fastify/)
- [Migrate a SQLAlchemy App From MySQL to PostgreSQL](https://getrush.ai/run/migrate-mysql-to-postgres/sqlalchemy/)
- [Replace node-fetch With Native fetch in a Node.js Library](https://getrush.ai/run/migrate-node-fetch-to-native-fetch/node-fetch/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
