☕️ Classic, reliable, trusted test framework for Node.js and the browser
chore: add v12 RC 1 release notes (#5848)
Mark Wiemer275ce519122c
diff --git a/docs/src/content/docs/blog/mocha-12.mdx b/docs/src/content/docs/blog/mocha-12.mdxnew file mode 100644index 00000000..dea6d43f--- /dev/null+++ b/docs/src/content/docs/blog/mocha-12.mdx@@ -0,0 +1,135 @@+---+description: Notable changes between Mocha 12 RC 1 and 11.7.4.+title: Mocha 12 RC 1 is here!+date: 2026-11-19T18:38:00Z # todo update time+excerpt: "Mocha 12 is the first release to follow our+ [even-odd major release pattern](https://github.com/mochajs/mocha/blob/main/MAINTAINERS.md#major-releases).+ 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."+---++import { PackageManagers } from "starlight-package-managers";++Mocha 12 is the first release to follow our+[even-odd major release pattern](https://github.com/mochajs/mocha/blob/main/MAINTAINERS.md#major-releases).+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](https://github.com/mochajs/mocha/blob/main/CHANGELOG.md).++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](https://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:++{/* todo validate after publish of RC 1, before publish of this post */}++<PackageManagers dev type="add" pkg="[email protected]" />++<a id="breaking-changes"></a>++## Breaking changes++- [Bump minimum Node.js version from 18.18.0 to 20.19.0 and 22.12.0+ (#5477)](https://github.com/mochajs/mocha/issues/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](#internal-modernization)).+- [Remove `util.inherits` / convert to classes+ (#5025)](https://github.com/mochajs/mocha/issues/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](https://mochajs.org/explainers/third-party-reporters/)+ page for details.+- [Remove `bin/_mocha` and convert `bin/` and entry points to ESM+ (#6017)](https://github.com/mochajs/mocha/pull/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)](https://github.com/mochajs/mocha/pull/6078):+ This should not be a breaking change for the vast majority of users,+ see [internal modernization](#internal-modernization).+- [Change the default of `--forbid-only` to check for process.env.CI+ (#5496)](https://github.com/mochajs/mocha/issues/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)](https://github.com/mochajs/mocha/pull/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)](https://github.com/mochajs/mocha/issues/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)](https://github.com/mochajs/mocha/issues/5512)+- [Add mocha.mjs export (#5527)](https://github.com/mochajs/mocha/issues/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)](https://github.com/mochajs/mocha/issues/5519)++## Notable fixes++- [Allow importing ESM interface and reporters (#5563)](https://github.com/mochajs/mocha/issues/5563)+- [Support file: URLs in loadFilesAsync (#5833)](https://github.com/mochajs/mocha/pull/5833)+- [Support modern RegExp flags in Mocha#grep (#5825)](https://github.com/mochajs/mocha/pull/5825)+- [Prevent diff hang on large/complex objects (#5898)](https://github.com/mochajs/mocha/pull/5898)+- [Surface global setup/teardown errors with a non-zero exit code (#5994)](https://github.com/mochajs/mocha/pull/5994)++<a id="internal-modernization"></a>++## Internal modernization++- As mentioned in [breaking changes](#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](https://github.com/mochajs/mocha/issues/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](https://github.com/mochajs/mocha/pull/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](https://github.com/search?q=repo%3Amochajs%2Fmocha+is%3Apr+is%3Amerged+merged%3A2025-10-02..2026-06-18+-author%3Amark-wiemer+-author%3Ajoshuakgoldberg+-author%3Avoxpelli+-author%3Arenovate%5Bbot%5D+-author%3Agithub-actions%5Bbot%5D+-author%3Adependabot%5Bbot%5D&type=pullrequests&s=updated&o=desc)!+We are also very grateful to our many+[financial donors](https://opencollective.com/mochajs).++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](https://github.com/mochajs/mocha/issues?q=sort%3Aupdated-desc+is%3Aissue+state%3Aopen+)+or [message us on Discord](https://discord.gg/KeDn2uXhER) for support 🤎++## References++- [CHANGELOG.md](https://github.com/mochajs/mocha/blob/main/CHANGELOG.md)