All jobs

Fix --compilers Is DEPRECATED and No Longer Supported After a Mocha Upgrade

Yes. An agent upgrades mocha, reproduces the refused --compilers flag, moves the Babel hook to --require, fixes the CI Node version and opens a PR.

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 clones the repository into its own cloud sandbox and reads how the tests are started. In a small library like developit/snarkdown, package.json has "test": "eslint src test && NODE_ENV=test mocha --compilers @babel/register", with mocha at ^5.1.1 (the lock file resolves 5.2.0), @babel/register 7.11.5, chai 3.5.0 and eslint 7.7.0 beside microbundle for the build. The Babel config lives in the same file under babel.env.test.presets, which is why the hook is needed: test/index.js uses import { expect } from 'chai' and import snarkdown from '../src'. .github/workflows/main.yml runs npm install, npm run prepare --if-present and npm test on actions/setup-node@v1 with node-version: 12.

Then it reproduces both states. With the locked mocha 5, npm test passes. After npm install -D mocha@latest, the same script fails before running anything, and the message depends on the version: mocha 6 and 10 print āœ– ERROR: --compilers is DEPRECATED and no longer supported. with a link to the compilers-deprecation wiki page, while mocha 12 no longer knows the flag at all and prints Error: No test files found: "@babel/register", because it reads the package name as a spec path. The agent quotes the message the repository's own upgrade produces.

The fix is one word in one script: mocha --require @babel/register. With that, mocha 12 runs the same suite and passes, and eslint is untouched. The agent also reads engines of the release it installed, node ^20.19.0 || >=22.12.0 for mocha 12, and sees that the workflow pins Node 12, so it moves setup-node to a current action version and a Node release the engine accepts; without that, the pull request would be green locally and red in CI for a reason that has nothing to do with the flag.

It leaves chai 3.5.0 and eslint 7.7.0 alone. Both still work with the new mocha in this run, and bumping them brings their own breaking changes (chai 5 is ESM only, for one), which belong in a separate pull request. The description lists them as the next candidates with the reason.

Start it with one API call

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

{
  "agent": "claude",
  "input": "The test script in this repository runs mocha with --compilers, which newer mocha releases refuse. Read package.json, the lock file, any mocha or babel configuration and the CI workflow first. Run the tests at the locked mocha version and record the result, then install the current mocha release and run the test script again, quoting the exact error. Change --compilers to --require with the same hook module, keep every other flag, and run the suite again until it passes. Check the installed mocha's engines field against the Node version the CI workflow uses and update the workflow only if it would not run that release. Do not upgrade other devDependencies; list the ones that look due with a reason. Open a pull request that quotes the failing and passing test output.",
  "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

What comes back is a pull request touching package.json, package-lock.json and .github/workflows/main.yml: the mocha range moved to the current major, --compilers replaced by --require, and the workflow's Node version raised to one the new mocha's engines field accepts. The description quotes the refused flag as the new mocha prints it, the passing summary line from before and after, and the engines value that justified the workflow edit.

A reviewer checks that the hook module is the same one (@babel/register), that no test file changed, that the eslint half of the script still runs first, and that the Node version in the workflow matches what the team deploys with. The run's record keeps the full test output of both runs, so the summary lines in the description are the terminal sessions, not a summary.

Run it on every Monday morning

Add an automation to the Project with this prompt and a schedule trigger, cron set to 0 9 * * 1 in your timezone. Each Monday one run upgrades mocha, runs the suite and opens one pull request on its own branch; a week where the suite cannot be made to pass ends needs_review with the failing output attached, and a week already on the current release opens nothing.

The same body can be sent from your own code with POST /o/{org}/sessions and an API key whenever a dependency bot opens a mocha bump you do not want to hand-fix; the key's webhook_url receives run.completed or run.failed with the session URL and the pull request when it ends.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

The error text is a moving target. The same stale flag is refused with one message on mocha 6, another on 10 and a misleading No test files found on 12, so a search for the line you saw often lands on advice for a different release. The agent installs the release your range resolves to today, runs your own script and quotes what it printed, and every command and its output stays in the run's record, so the pull request argues from the actual failure rather than from a thread about an older one.

It is also a change that touches CI as much as the code. The flag fix alone would have passed on a laptop and failed on the Node 12 runner, and the agent catches that by reading engines instead of waiting for the red check. On Rush the run happens in its own sandbox, nothing else competes for the machine, and what comes back is one reviewed pull request with the before and after output, ready to merge.

Frequently asked questions

Why does mocha 12 say No test files found instead of mentioning --compilers?

Mocha 6 through 10 kept a guard that recognised the removed flag and printed a deprecation error with a migration link. Mocha 12 dropped the guard, so --compilers is an unknown option and the argument after it, @babel/register, is read as a file pattern that matches nothing. Either way the fix is the same: --require with the same module.

Is --require really equivalent to --compilers?

For a Babel hook, yes. --compilers js:babel-register or --compilers @babel/register loaded the module before the tests so .js files were transpiled on require; --require @babel/register does exactly that. The extension prefix is gone because the hook registers its own extensions.

Will it bump chai and eslint while it is there?

No. The prompt says to leave other devDependencies and list the ones that look due. In this repository that is chai 3 and eslint 7, and each has its own breaking changes, so each gets its own pull request where its own test output can be read.

What if the repository has a .mocharc file instead of flags?

Then the agent edits the compilers key there, since the flag and the config key were removed together, and keeps the rest of the file. It reads .mocharc.*, package.json and any test/mocha.opts before deciding where the hook is declared.

More Mocha jobs

More jobs like this: Upgrade dependencies weekly

Keep reading