TL;DR

Mocha now uses ECMAScript Modules (ESM) internally, and browser tests have been migrated to Playwright (a testing framework) for improved reliability.

Breaking

• ESM Root Package: The root package.json type has been changed to module. (This affects how Mocha is imported and may require changes to your build process if you directly import Mocha’s code.)

New

• Playwright Integration: Browser tests now use Playwright, replacing Karma. (This should result in more stable and faster browser testing.)
• Documentation Updates: A new blog has been added. (Provides a new channel for announcements and in-depth information.)

Fixes Worth Knowing

• Watch Mode Reliability: Improved stability of the file watcher in watch mode. (Reduces false positives and ensures tests re-run when files change.)
• Cursor in Watch Failure: Restored cursor visibility in the terminal when watch mode fails. (Improves the user experience when debugging test failures.)

TL;DR

Mocha now displays more informative error messages when using TypeScript with ts-node (a TypeScript execution tool), helping you debug compilation issues faster.

Fixes Worth Knowing

Mocha now surfaces errors from ts-node during compilation, providing clearer feedback when TypeScript code fails to build before running tests.

TL;DR

Mocha is transitioning to ECMAScript Modules (ESM), removing CommonJS binaries for a more modern JavaScript experience.

Breaking

• The _mocha binary has been removed, and all entry points are now ESM. (This affects how you run Mocha from the command line and import it in your projects.)

New

• Mocha now supports direct file paths when looking up files. (Improves file resolution.)

Fixes Worth Knowing

• Fixed an issue preventing large or complex objects from causing hangs during diffs. (Improves test result readability.)
• Global setup/teardown errors now result in a non-zero exit code. (Ensures failures are correctly reported.)
• LookupFiles() now returns string[] for direct file paths. (Improves file resolution.)

Before You Upgrade

• If you directly execute _mocha in your scripts or CI, update them to use the ESM-compatible entry points (e.g., node --experimental-modules node_modules/mocha/bin/mocha).
• Review your import statements to ensure compatibility with ESM if you are importing Mocha directly in your code.

TL;DR

Mocha now highlights test failures specifically occurring in browser environments, making it easier to diagnose platform-specific issues.

New

• Browser Failure Highlighting: Test results now clearly indicate failures happening in browsers.

Fixes Worth Knowing

• Fixed an issue where tests with circular dependencies (complex object structures) would fail when running in parallel.
• Improved HTML reporter links to accurately point to test files.
• Resolved compatibility issues with older browsers by removing a newer CSS selector.
• Addressed issues with invalid package.json files preventing Mocha from loading configurations.

Before You Upgrade

If you rely on the exports interface, note that it is not supported in browser environments.

TL;DR

Mocha now includes security updates by upgrading the glob dependency, addressing a known vulnerability.

Fixes Worth Knowing

Resolved an issue with deprecated warnings in GitHub Actions. Documentation has been improved with corrected examples and clearer contributor guidelines.

TL;DR

Mocha now handles reporter loading and dry-run mode more reliably, preventing crashes and improving stability when running tests.

Fixes Worth Knowing

• Reporter loading errors are now more accurate.
• Running Mocha with the dry-run flag (testing without execution) is more stable.

TL;DR

Mocha now supports dynamically generating tests with top-level await in ESM (ECMAScript Modules) files, improving flexibility for modern JavaScript projects.

New

• Dynamically generate tests using top-level await with ESM files.
• Improved support for root hook plugins when running tests in parallel.

Fixes Worth Knowing

• Watch mode no longer crashes when reloading files.
• CLI file parsing errors now include error codes for easier debugging.

Before You Upgrade

Update your test files to use the latest default file extensions.

TL;DR

Mocha now allows running tests multiple times within a single instance, improving efficiency for scenarios like retries or rapid development cycles.

Fixes Worth Knowing

Several fixes improve reliability: --forbid-only now correctly prevents running it.only tests, multiple done() calls in asynchronous tests are handled correctly, and configuration file loading is more robust. Invalid reporter warnings are also now displayed properly.

TL;DR

Mocha now includes critical security updates, patching vulnerabilities in its dependencies to protect your testing environment.

Fixes Worth Knowing

Updated dependencies address security vulnerabilities, improving the overall stability and security of your test runs. (Dependencies are external libraries)

TL;DR

Mocha now supports native ECMAScript Modules (JavaScript modules) in Node.js, allowing you to import tests directly.

Breaking

• ESM support has limitations: --watch, --require, custom reporters, custom UIs, and mocharc configuration are not yet compatible. (Testing setup/tools)

New

• Native ESM support allows using import statements in test files. (JavaScript modules)

Before You Upgrade

• Ensure you are using Node.js v12.11.0 or higher; Node.js versions below 13.2.0 require the --experimental-modules flag.

TL;DR

Mocha 6.0 introduces a new configuration system with support for .mocharc.js, .mocharc.json, and package.json files, offering more flexible and prioritized test setup.

Breaking

• Node.js v4.x is no longer supported.
• --grep and --fgrep cannot be used together.
• --compilers option is removed.
• -d is no longer an alias for --debug.
• --watch-extensions requires explicitly including js.
• tap reporter now emits error messages.
• Conditional skips in before hooks now skip subsequent hooks and tests.
• mocha.opts parsing now throws an error if the file isn’t found.
• Instantiating a Base-extending reporter requires a Runner parameter.
• Error objects now have a code property; use this instead of message for reliable error type checking.

New

• Mocha now supports configuration files (JS, JSON, YAML, or package.json) with a defined priority order.
• Node/V8 flags can now be passed directly to the mocha executable

TL;DR

Mocha now supports comments within your mocha.opts configuration file, improving readability and organization.

New

• Mocha now includes dedicated API documentation (developer reference materials).

Fixes Worth Knowing

• Using the --bail flag now correctly stops execution after a failure, even within before hooks (setup code).

TL;DR

Mocha now computes diffs (code comparison) eagerly, preventing misleading output, and offers more flexibility with the --no-diff flag to disable diffs entirely.

Fixes Worth Knowing

• xit (skipped test) now correctly returns its test object.
• The progress reporter now accepts custom reporter options.
• --help now works even when using a mocha.opts configuration file.

New

• Mocha's API setters now also function as getters when called without arguments, simplifying property access.

TL;DR

Mocha now correctly handles unicode characters and invalid entities in the XUnit reporter (test output format), improving the reliability of test results.

Fixes Worth Knowing

• Fixed an issue where xit (skipped test) wasn’t available when using the require interface.
• Resolved failures related to using Mocha with AMD (Asynchronous Module Definition) loaders.

TL;DR

Mocha now supports ES2017 async/await testing natively, simplifying asynchronous test code.

Breaking

• Removed require support for test files (use import statements).
• Dropped Node.js v0.8 and v4 support (ensure compatible Node version).

New

• Added support for async/await in tests, allowing cleaner asynchronous code.
• Improved stack traces for better debugging.

Fixes Worth Knowing

• Fixed a bug where tests would sometimes hang when using beforeEach and afterEach hooks.
• Resolved issues with test ordering in some cases.

Before You Upgrade

• Update your test files to use import statements instead of require.
• Ensure you are using a supported Node.js version (v6 or higher).