Mocha 12 RC 1 is here!

Jun 20, 2026

Mocha 12 is the first release to follow our even-odd major release pattern. As an even release, Mocha 12 introduces very few breaking changes: We’ve bumped our Node floor, removed some long-deprecated features, and modernized a bit, but everything else works just as before.

These notes cover all changes in our first release candidate, 12.0.0-rc.1. The baseline is 11.7.4, after which we started releasing betas. To view the full changelog, see CHANGELOG.md on Github.

As a release candidate, RC 1 contains all the features that will be in 12.0.0. We will work to fix bugs for future release candidates, then release a stable 12.0.0 when it’s ready.

We will continue to support critical bugfixes in Mocha 11 while customers upgrade to Mocha 12. We’ve also deployed v11.mochajs.org for users that may rely on Mocha 11 in the long-term.

You can try the RC now with a standard install:

npm

npm i -D mocha@12.0.0-rc.1

pnpm

pnpm add -D mocha@12.0.0-rc.1

yarn

yarn add -D mocha@12.0.0-rc.1

Breaking changes

• Bump minimum Node.js version from 18.18.0 to 20.19.0 and 22.12.0 (#5477): We know that Node 20 is now EOL, but we didn’t want to jump 2 LTS versions in one release. Mocha 13 will drop support for Node 20. The new minimum versions are the lowest Node versions that support require(esm) (see internal modernization).
• Remove util.inherits / convert to classes (#5025): Through Mocha 11, reporters inherited behavior through util.inherits. This was deprecated a long time ago. Reporters now inherit through canonical class syntax. This means that the syntax for custom reporters has changed, but the core behavior is the same. See the updated third-party reporters page for details.
• Remove bin/_mocha and convert bin/ and entry points to ESM (#6017): The _mocha entry point had been kept as a workaround for old coverage providers. Swapping path/to/_mocha with mocha should work without issue.
• Change root package.json type to module (#6078): This should not be a breaking change for the vast majority of users, see internal modernization.
• Change the default of --forbid-only to check for process.env.CI (#5496): This should improve CI runs, but rare use-cases may need to explicitly set --no-forbid-only to restore the previous default behavior.
• Remove unused legacy errors.js functions (#5835): The public function createInvalidPluginError has been deprecated for years. Callers should use createInvalidLegacyPluginError instead, which has the exact same contract and behavior.
• Cleanup references of --compilers (#5403): This flag had been deprecated for a long time. It had not had any impact on behavior for years. It is now removed from the codebase.

Notable new features

• Allow FIFOs as test files (#5512)
• Add mocha.mjs export (#5527): This has since been renamed mocha.js but it still works for use in the browser!
• Add --fail-hook-affected-tests option to report skipped tests as failed (#5519)

Notable fixes

• Allow importing ESM interface and reporters (#5563)
• Support file: URLs in loadFilesAsync (#5833)
• Support modern RegExp flags in Mocha#grep (#5825)
• Prevent diff hang on large/complex objects (#5898)
• Surface global setup/teardown errors with a non-zero exit code (#5994)

Internal modernization

• As mentioned in breaking changes, Mocha is now an ESM-first package, using "type": "module" instead of "type": "commonjs" in package.json. This should not be a breaking change for the vast majority of users; CJS consumers can still require('mocha') just as before, thanks to new support in Node 20.19.0 and 22.12.0. We’ve marked it as “breaking” for users that depend on Mocha’s internal structure for any reason. ESM is the modern, canonical way of managing modules, supported officially by the ECMAScript spec. CJS was always a placeholder approach until a better solution came along. (#5400)
• Mocha now uses Playwright instead of Karma for its internal tests. This is not a user-facing change in any way, but it means that Mocha contributors can now use a modern browser automation library instead of the long-deprecated Karma approach. This will help us better support browser-based testing in the future. (#6031)

Thank you!

Mocha development could not continue without the support of contributors who have opened issues, submitted PRs, and commented in discussions. 98 merged PRs for Mocha 12 were opened by community members! We are also very grateful to our many financial donors.

Mocha continues to thrive thanks to all of these generous contributions. Thank you.

Questions, comments, concerns?

As always, you can open an issue on GitHub or message us on Discord for support 🤎

References

• CHANGELOG.md

Maintenance Reboot