# 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 Rush](https://cloud.getrush.ai/run/fix-configuration-via-mocha-opts-is-deprecated/mocha/). Opens 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`

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

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

- [Fix --compilers Is DEPRECATED and No Longer Supported After a Mocha Upgrade](https://getrush.ai/run/fix-mocha-compilers-is-deprecated-and-no-longer-supported/mocha/)
- [Migrate Mocha Tests to the Built-In Node.js Test Runner](https://getrush.ai/run/migrate-mocha-to-node-test/mocha/)
- [Migrate a Node.js Library from Mocha to Vitest](https://getrush.ai/run/migrate-mocha-to-vitest/mocha/)

## More jobs like this: Fix a bug from an alert

- [Fix "Copy Plugin has been initialized using an options object that does not match the API schema"](https://getrush.ai/run/fix-copy-plugin-options-does-not-match-the-api-schema/copy-webpack-plugin/)
- [Fix "Could not find method compile() for arguments" in Gradle 7 and Later](https://getrush.ai/run/fix-could-not-find-method-compile/gradle/)
- [Fix `Call to undefined function create_function()` after moving to PHP 8](https://getrush.ai/run/fix-create-function-removed/php/)

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