TL;DR

Mocha now correctly respects describe().timeout() settings, ensuring tests are properly timed out when they exceed specified limits.

Fixes Worth Knowing

Tests on Windows now use native APIs instead of wmic, improving reliability and potentially performance.

TL;DR

Mocha is migrating to ECMAScript Modules (ESM), improving modern JavaScript compatibility and developer experience.

Breaking

• Removed unused legacy functions from errors.js. (May affect tests directly using those functions)

New

• Added a guide for setting up Mocha with TypeScript. (Helps users adopt TypeScript for testing)

Fixes Worth Knowing

• Corrected issues in error codes, CLI defaults, and configuration documentation. (Improves usability and accuracy of Mocha’s behavior)
• Updated dependencies including ESLint, Sinon, and NYC. (Ensures compatibility and benefits from upstream improvements)

Before You Upgrade

• Review your tests for any direct usage of the removed functions from errors.js and update accordingly.

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).