All jobs

Fix "Configuration via mocha.opts is DEPRECATED" and the --opts error on Mocha 8 and later

Yes. An agent moves the settings in mocha.opts to a .mocharc file, drops the --opts flag from every test script, and runs the whole suite on the current Mocha.

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 how the tests are wired before touching Mocha. In a small browser library like florian/cookie.js, package.json runs four suites, test:umd, test:umd:min, test:cjs and test:esm, each as mocha --opts tests/mocha.opts tests/builds/<build>.js (the ESM one adds -r babel-core/register), with pretest building the bundles through rollup -c first; the dev dependency is "mocha": "^5.0.0". tests/mocha.opts holds one line, --reporter dot. The suites load dist/cookie.umd.js, dist/cookie.cjs.js and the others through tests/shared.js under jsdom, so the file being migrated is small but every script depends on it.

Then it runs the suite on each Mocha major to show what the warning becomes. With the installed Mocha 5 all four scripts pass. Mocha 7 prints DeprecationWarning: Configuration via mocha.opts is DEPRECATED and will be removed from a future version of Mocha. Use RC files or package.json instead. and still passes. Mocha 8 prints its usage text and ends with ERROR: --opts: configuring Mocha via 'mocha.opts' is DEPRECATED and no longer supported. Please use a configuration file instead. Mocha 12 no longer knows the flag at all, treats tests/mocha.opts as a spec file and fails with SyntaxError: Unexpected identifier 'dot' from line 1 of that file, which is the confusing version of the same problem.

The fix is a config file and four script edits. The agent writes .mocharc.yml with reporter: dot, removes --opts tests/mocha.opts from each script so they read mocha tests/builds/umd.js and so on, deletes tests/mocha.opts, and installs the current Mocha. All four suites then pass on Mocha 12 with the same counts as on Mocha 5. The reporter, the only setting the file carried, still applies because Mocha reads .mocharc.yml from the project root on every invocation.

It also reads what the upgrade drags along. Mocha 12's engines field asks for Node ^20.19.0 || >=22.12.0, and .travis.yml pins node_js: 10.16.0, so the CI file has to move with the dependency or the upgrade cannot be merged; the agent states the requirement and proposes the Node line in the same pull request, separately marked, rather than hiding it.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Our Node project prints \"Configuration via mocha.opts is DEPRECATED\" and fails with an --opts error on a newer Mocha. Find every script that passes --opts and every setting in mocha.opts, move those settings to a .mocharc file, remove the flag and the old file, and upgrade Mocha to the current release. Run every test script before and after and report the test counts. Say what Node version the new Mocha requires and whether our CI config meets it, and open a pull request with the 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

A pull request that adds .mocharc.yml, deletes tests/mocha.opts, edits the four test:* scripts in package.json, and moves the mocha dev dependency to the current major. The description shows the suite on Mocha 5 and on Mocha 12 with the count from each of the four scripts, quotes the deprecation line from Mocha 7, the hard error from Mocha 8 and the misleading SyntaxError from 12, and names Mocha 12's Node requirement against the Node pinned in .travis.yml.

A reviewer checks that the reporter still applies, that no other option lived in the old file, and decides whether to take the CI Node bump in the same change.

Run it on every Dependabot pull request that bumps mocha

The hard error lands with the major bump, so the trigger is the pull request that moves Mocha past 7. An automation with a github trigger on pull_request.opened and pull_request.synchronize runs this prompt on each one, with the event appended after the prompt, and pushes the .mocharc.yml and script changes onto the bump's branch when the suite fails on --opts.

For many packages that still ship a mocha.opts, your server sends this request once per repository, each with its own UUID as request_id so a retry returns the run already started, and reads each run.completed webhook; a key starts at most max_concurrent runs at once and queues the rest.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

The same removed flag produces three different messages across Mocha majors, and the newest one, a SyntaxError inside the options file, does not mention --opts at all. In a Rush sandbox the agent installs each major, runs the real suite under it and keeps the output, so the pull request explains what a developer will see at every step of the upgrade.

A test-runner migration is only proven by the test counts. The agent runs all four scripts before and after, including the one that registers Babel for the ESM build, and shows they pass with the same numbers on the current Mocha.

Frequently asked questions

Which config file format should I use?

Mocha reads .mocharc.yml, .mocharc.json, .mocharc.js or a mocha key in package.json. The agent uses a YAML file at the project root with one key per old flag; for a single --reporter dot that is one line, and the file is picked up by every script without being named.

Why does Mocha 12 report a SyntaxError instead of mentioning --opts?

Mocha 8 removed the flag and printed an explicit error for it. By 12 the flag is unknown, so --opts is ignored and the path after it is treated as a test file; Mocha then tries to load tests/mocha.opts as JavaScript and fails on its first line. The pull request quotes both forms so the next person searching either one finds the fix.

Do I have to upgrade Node as well?

Mocha 12 declares Node ^20.19.0 || >=22.12.0 in its engines field. If your CI pins an older Node, as this repository's .travis.yml does with 10.16.0, the CI config has to move too. The agent says so and leaves the choice of Node line to you.

Will the -r babel-core/register script still work?

Yes. -r is still a Mocha flag, so the ESM script keeps it on the command line while the reporter comes from .mocharc.yml. The pull request shows that script passing with the same count as the other three.

More Mocha jobs

More jobs like this: Fix a bug from an alert

Keep reading