docs: publish v12 stable blog

docs/src/content/docs/blog/mocha-12-stable.mdx

@@ -0,0 +1,274 @@
+---
+date: 2026-09-01T00:00:00Z
+description: Notable changes in Mocha 12
+excerpt: "Mocha 12 is ready for use in production environments.
+  Below is a migration guide, including breaking changes,
+  notable new features, and some bugfixes we're proud of."
+title: Mocha 12 is now available
+---
+
+import { PackageManagers } from "starlight-package-managers";
+
+Mocha 12 is ready for use in production environments.
+
+<PackageManagers dev type="add" pkg="mocha@12.0.0" />
+
+Below is a migration guide, including breaking changes, notable new features,
+and some bugfixes we're proud of.
+
+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 who rely on Mocha 11 in the long-term.
+
+## Breaking changes
+
+The changes in Mocha 12 should require few, if any, changes in user applications.
+Most end-users should not be affected by Mocha 12's breaking changes.
+A small subset of programmatic integrators may need to perform small updates to work with some API updates.
+
+:::tip
+If you have questions or otherwise need assistance updating an application to Mocha 12,
+please feel free to ask for help on our [community Discord server](https://discord.com/invite/KeDn2uXhER).
+:::
+
+### Minimum Node.js version increases
+
+Mocha 12 updates the minimum Node.js versions supported to `^20.19.0 || >=22.12.0`.
+
+Those new minimum versions are intentionally the lowest Node.js versions that support `require(esm)`.
+We intentionally chose those versions so that programmatic integrators can continue to `require("mocha")`, though we do recommend updating to ECMAScript Modules (ESM) if possible.
+
+Accordingly, Mocha's minimum supported browser versions are those that were stable as of [Node.js 20.0.0](https://nodejs.org/en/blog/release/v20.0.0)'s release on April 18, 2023:
+[Chrome 112](https://developer.chrome.com/blog/new-in-chrome-112), [Edge 112](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-relnote-archive-stable-channel#version-1120172248-april-14-2023), [Firefox 112](https://www.mozilla.org/en-US/firefox/112.0/releasenotes), and [Safari 16.4](https://developer.apple.com/documentation/safari-release-notes/safari-16_4-release-notes).
+
+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.
+
+See [#5358 🧹 Versioning: Bump minimum Node.js version from 18.18.0 to 20.19.0](https://github.com/mochajs/mocha/issues/5477) and [feat!: bump minimum Node.js version from 18.18.0 to 20.19.0 (#5477)](https://github.com/mochajs/mocha/pull/5477) for more details.
+
+### ECMAScript Modules (ESM) package
+
+Mocha is now an ECMAScript Modules (ESM) package.
+Moving to ESM allows the internal code to integrate better with more modern dev tooling.
+For example, static analysis tools such as ESLint, Knip, and TypeScript are better able to analyze ESM,
+which will help us detect bugs and unused code in future versions of Mocha.
+
+Most users should not see any change from the ESM migration.
+We have identified some edge cases from programmatic usage of Mocha that require some changes:
+
+See [#5400 🛠️ Repo: Switch from CJS to ESM internally ](https://github.com/mochajs/mocha/issues/5400) for more details.
+
+#### Removed legacy entrypoint
+
+One `_mocha` entry point had been kept in older versions of Mocha as a workaround for old coverage providers.
+It is now removed.
+Swapping `path/to/bin/_mocha` with `mocha` should work the same:
+
+```diff
+- node path/to/bin/_mocha
++ node path/to/bin/mocha
+```
+
+Other package entrypoints for Mocha should work as before.
+Mocha 12's `package.json` still does not use ESM [`"exports"`](https://nodejs.org/api/packages.html#exports) to restrict imports of source files.
+We will wait until Mocha 13 to switch to legacy permissive [`"main"`](https://nodejs.org/api/packages.html#main) field.
+
+See [#5970 🛠️ Repo: Convert bin/ and top-level entry points to ESM](https://github.com/mochajs/mocha/issues/5970) and [#6017 feat!: remove bin/\_mocha and convert bin/ and entry points to ESM](https://github.com/mochajs/mocha/pull/6017) for more details.
+
+#### `require('mocha')` now returns an object
+
+Running `require('mocha')` in CommonJS (CJS) code used to return the `Mocha` function directly.
+It now returns an object, with a `Mocha` property.
+
+To work around this, change:
+
+```diff
+- const Mocha = require('mocha');
++ const { Mocha } = require ('mocha');
+```
+
+See [#6245 🐛 Bug: require('mocha') now returns an object, not a function (12.0.0-rc.6)](https://github.com/mochajs/mocha/issues/6245) for more details.
+
+### Native Node.js CLI parsing
+
+Through Mocha 11, [`yargs`](https://www.npmjs.com/package/yargs) and its related packages parsed command-line input to Mocha.
+mocha now uses native [Node.js `util.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig).
+
+The new approach should be functionally the same,
+with potential minor formatting differences
+in human-facing output like `--help`.
+
+These were marked as breaking changes out of an abundance of caution.
+
+- [feat!: replace yargs-parser in CLI option loading (#6124)](https://github.com/mochajs/mocha/pull/6124)
+- [feat!: replace yargs-unparser in CLI respawn paths (#6125)](https://github.com/mochajs/mocha/pull/6125)
+- [refactor!: replace yargs with Node.js util.parseArgs (#6164)](https://github.com/mochajs/mocha/pull/6164)
+
+### `--forbid-only` defaults to `process.env.CI`
+
+Mocha's [`--forbid-only` CLI flag](/running/cli/#--forbid-only) fails test runs if an [`.only`](/declaring/exclusive-tests/#_top) is declared.
+Using the flag is useful to make sure `.only`s aren't accidentally kept in changes.
+
+`--forbid-only` previously defaulted to `false`.
+Its new default is now whether an environment variable named `CI` is truthy.
+This matches other test runner behaviors such as [Vitest's `allowOnly`](https://vitest.dev/config/allowonly).
+
+If you intentionally want to use `.only` in CI,
+explicitly set `--no-forbid-only` to restore the previous default behavior.
+
+```shell
+npx mocha --no-forbid-only
+```
+
+See [#5299 🚀 Feature: Exit with code 1 when .only is used by default in CI (--forbid-only)](https://github.com/mochajs/mocha/issues/5299) and [feat!: change the default of --forbid-only to check for process.env.CI- #5496](https://github.com/mochajs/mocha/pull/5496) for more details.
+
+### Replacing `util.inherits` with classes
+
+Through Mocha 11, reporters inherited behavior from a base object through the legacy [Node.js `util.inherits`](https://nodejs.org/api/util.html#utilinheritsconstructor-superconstructor).
+`util.inherits` has subtly different behavior from ES2015 JavaScript classes was deprecated in Node.js many years ago.
+
+Reporters now inherit through canonical JavaScript `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](/explainers/third-party-reporters/)
+page for updated usage instructions.
+
+See [#5025 🐛 Remove `util.inherits` / convert to classes](https://github.com/mochajs/mocha/issues/5025) for more details.
+
+### Internal cleanups
+
+The following cleanups should be functionally the same for users, but
+are marked as breaking changes out of an abundance of caution.
+
+- [Replace `he` dependency with manual HTML encoding (#6129)](https://github.com/mochajs/mocha/issues/6129): `he` was used for HTML encoding in some reporters, and in the exported `escape` function.
+- [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 same contract and behavior.
+
+### Deprecated CLI flag removals
+
+The following two flags have both been deprecated for a long time.
+They have not had any impact on behavior for years.
+They are now removed from the codebase.
+
+- [Cleanup references of `--compilers` (#5403)](https://github.com/mochajs/mocha/issues/5403)
+- [Cleanup references of `--opts` (#5243)](https://github.com/mochajs/mocha/issues/5243)
+
+## Notable new features
+
+### Executing FIFOs as test files
+
+A "FIFO", or **first**-**in** **first**-**out**, is a file piped directly to a command in a terminal.
+This can be convenient for quickly running small pieces of code in Mocha:
+
+```shell
+npx mocha --preserve-symlinks <(echo 'it("t", () => require("node:assert").equal(1, 1))')
+```
+
+See [#5511 🚀 Feature: execute tests from FIFOs](https://github.com/mochajs/mocha/issues/5511) and [feat: allow FIFOs as test files](https://github.com/mochajs/mocha/pull/5512) for more details.
+
+### ESM export for browsers
+
+Mocha has long supported working in browsers.
+But until recently, did not have a canonical way to `import` from within a `<script type="module">`.
+Mocha 12 now canonically supports an ESM browser import:
+
+```html
+<script type="module">
+  // TODO: Verify this & add a test!
+  import * as mocha from "./node_modules/mocha/mocha.js";
+
+  mocha.setup("bdd");
+  await import("./unit-test.js");
+  mocha.run();
+</script>
+```
+
+See [#5211 🚀 Feature: Ability to import mocha from ESM in the browser](https://github.com/mochajs/mocha/issues/5211) and [feat: add mocha.mjs export (#5527)](https://github.com/mochajs/mocha/pull/5527) for more details.
+
+### Added `--fail-hook-affected-tests` CLI flag
+
+Mocha allows declaring "hooks" like `before()` and `afterEach()` to run logic before and/or after tests.
+By default, thrown errors in those hooks don't not fail their related tests.
+This is unintuitive for many users and can mask important failures in shared test logic.
+
+Mocha 12 introduces a new [`--fail-hook-affected-tests` CLI flag](running/cli/#--fail-hook-affected-tests) that causes failures in hooks to fail their affected tests:
+
+```shell
+npx mocha --fail-hook-affected-tests
+```
+
+We recommend enabling this flag.
+It will be enabled by default in a future major version of Mocha.
+
+See [#4392 🚀 Feature: Failures in before() and beforeAll() should cause all impacted tests to be reported as failed](https://github.com/mochajs/mocha/issues/4392) and [feat: add --fail-hook-affected-tests option to report skipped tests as failed (#5519)](https://github.com/mochajs/mocha/pull/5519) for more details.
+
+## Notable fixes
+
+### Default imported interfaces and reporters
+
+Mocha allows users to load in custom [interfaces](/interfaces/about) and [reporters](/reporters/about) for test runs.
+Previously they had to be exported with CommonJS (CJS) semantics.
+However, ECMAScript Modules (ESM) semantics prefer `export default ...` (`module.exports.default = ...`).
+This use case is now supported for both interfaces and reporters.
+
+See [#5562 🐛 Bug: Can't ESM (default) import custom interfaces and reporters](https://github.com/mochajs/mocha/issues/5562) and [fix: allow importing ESM interface and reporters](https://github.com/mochajs/mocha/pull/5563) for more details.
+
+### Adding URLs with `loadFilesAsync`
+
+Mocha's Node.js API includes a [`loadFilesAsync` method](https://legacy.mochajs.org/api/mocha#loadFilesAsync) to import and run specified test files.
+It previously only supported local pathnames of files as added by the [`addFile` method](https://legacy.mochajs.org/api/mocha#addFile).
+Attempting to load in a file with a standard `file://...` URL would throw an error.
+This is now corrected to work as expected.
+
+See [#4993 🐛 Bug: esm-utils (mocha.addFile) should support URL](https://github.com/mochajs/mocha/issues/4993) and [fix: support file: URLs in loadFilesAsync (#5833)](https://github.com/mochajs/mocha/pull/5833) for more details.
+
+### Grepping with modern RegExp flags****
+
+Mocha supports a [`grep` CLI flag](https://mochajs.org/running/cli/#--grep-regexp--g-regexp) and [`grep` Node.js API method](https://legacy.mochajs.org/api/mocha#grep) for matching files on disk with regular expressions.
+Mocha's internal logic validates those regular expressions, but hadn't been updated since before the modern [`u`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicode "RegExp unicode flag"),
+[`s`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/dotAll "RegExp dotAll flag"),
+and [`v`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets "RegExp unicodeSets flag") RegExp flags were added to JavaScript.
+The validation logic is now updated to allow those modern flags.
+
+See [#5826 🐛 Bug: Mocha#grep fails to parse modern RegExp flags (u, s, v) from string input](https://github.com/mochajs/mocha/issues/5826) and [fix: support modern RegExp flags in Mocha (#5825)](https://github.com/mochajs/mocha/pull/5825) for more details.
+
+### Diff hangs on large object comparisons
+
+If a thrown error in a test contains `.actual` and `.expected` properties, Mocha will show a rich stringified diff of the differences.
+This is implemented by common assertion libraries such as [Chai](https://www.chaijs.com).
+
+Previously, if one or both of those properties contained very complex and/or large objects,
+Mocha's diff generation could hang indefinitely during stringification.
+Mocha 12 fixes this.
+
+See [#1624 🐛 Bug: Comparing buffers hangs when computing the diff report](https://github.com/mochajs/mocha/issues/1624) and [fix: prevent diff hang on large/complex objects (#5898)](https://github.com/mochajs/mocha/pull/5898) for more details.
+
+### Non-zero exit codes on setup and teardown errors
+
+Mocha provides [global fixtures](https://mochajs.org/features/global-fixtures) so that test suites may run code once on setup or teardown.
+Previously, if an error was thrown in a global fixture, it would be ignored and Mocha would continue to run tests.
+This is unintuitive for many users and can mask important failures in shared test logic.
+Mocha 12 will now exit with a non-zero status code on global fixture errors.
+
+See [#5208 🐛 Bug: Error in mochaGlobalTeardown is swallowed and exits with code 0](https://github.com/mochajs/mocha/issues/5208) and [fix: surface global setup/teardown errors with a non-zero exit code (#5994)](https://github.com/mochajs/mocha/pull/5994) for more details.
+
+## Thank you!
+
+Mocha development could not continue without the support of contributors
+who have opened issues, submitted PRs, and commented in discussions.
+During development of Mocha 12, we merged [100+ PRs from community members](https://github.com/search?q=repo%3Amochajs%2Fmocha+is%3Apr+is%3Amerged+merged%3A2025-10-02..2026-08-27+-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)