Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ 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.mdx
new file mode 100644
index 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)