☕️ Classic, reliable, trusted test framework for Node.js and the browser
docs: fix correctness issues in error codes, CLI defaults, and config docs (#5860)
Mostafa Nazaribd54205584ab
diff --git a/docs/src/content/docs/explainers/compilers-deprecation.mdx b/docs/src/content/docs/explainers/compilers-deprecation.mdxindex 8ec30b90..b9157d8f 100644--- a/docs/src/content/docs/explainers/compilers-deprecation.mdx+++ b/docs/src/content/docs/explainers/compilers-deprecation.mdx@@ -34,7 +34,7 @@ Here's a list of popular compilers/transpilers:- LiveScript: `--compilers ls:livescript` becomes `--require livescript`- (feel free to add more examples!)-You'll have to handle file extensions as well. Mocha, by default, only loads `.js` files when given a directory (and the default directory is `test`). Therefore, to use a _different_ file extension (such as `.coffee` or `.ts`), you will need to supply a _glob_ instead of simply a directory. If this was how you ran Mocha pre-v4:+You'll have to handle file extensions as well. Mocha, by default, only loads `.js`, `.cjs`, and `.mjs` files when given a directory (and the default directory is `test`). Therefore, to use a _different_ file extension (such as `.coffee` or `.ts`), you will need to supply a _glob_ instead of simply a directory. If this was how you ran Mocha pre-v4:```bash$ mocha --compilers coffee:coffee-script/register --recursive ./testdiff --git a/docs/src/content/docs/explainers/nodejs-native-esm-support.mdx b/docs/src/content/docs/explainers/nodejs-native-esm-support.mdxindex a7cf7056..c0fc25ee 100644--- a/docs/src/content/docs/explainers/nodejs-native-esm-support.mdx+++ b/docs/src/content/docs/explainers/nodejs-native-esm-support.mdx@@ -28,7 +28,6 @@ More information can be found in the [Node.js documentation](https://nodejs.org/- [Watch mode](/running/cli#--watch--w) does not support ES Module test files- [Custom reporters](/reporters/third-party) and [custom interfaces](/interfaces/third-party) can only be CommonJS files-- [Configuration file](/running/configuring) can only be a CommonJS file (`.mocharc.js` or `.mocharc.cjs`)- Mocha in Node.js version 24.4.0 or older [silently ignored top level errors in ESM files](https://github.com/mochajs/mocha/issues/5396).If you cannot upgrade to a newer Node.js version, you can add `--no-experimental-require-module` to the `NODE_OPTIONS` environment variable.- When using module-level mocks via libs like `proxyquire`, `rewiremock` or `rewire`, hold off on using ES modules for your test files.diff --git a/docs/src/content/docs/features/error-codes.mdx b/docs/src/content/docs/features/error-codes.mdxindex 28abfb70..6ad7288a 100644--- a/docs/src/content/docs/features/error-codes.mdx+++ b/docs/src/content/docs/features/error-codes.mdx@@ -10,12 +10,21 @@ When Mocha itself throws exception, the associated `Error` will have a `code` prWhere applicable, consumers should check the `code` property instead of string-matching against the `message` property.The following table describes these error codes:-| Code | Description |-| ---------------------------------- | ------------------------------------------------------------ |-| `ERR_MOCHA_INVALID_ARG_TYPE` | wrong type was passed for a given argument |-| `ERR_MOCHA_INVALID_ARG_VALUE` | invalid or unsupported value was passed for a given argument |-| `ERR_MOCHA_INVALID_EXCEPTION` | a falsy or otherwise underspecified exception was thrown |-| `ERR_MOCHA_INVALID_INTERFACE` | interface specified in options not found |-| `ERR_MOCHA_INVALID_REPORTER` | reporter specified in options not found |-| `ERR_MOCHA_NO_FILES_MATCH_PATTERN` | test file(s) could not be found |-| `ERR_MOCHA_UNSUPPORTED` | requested behavior, option, or parameter is unsupported |+| Code | Description |+| ----------------------------------------- | --------------------------------------------------------------------- |+| `ERR_MOCHA_FATAL` | an unrecoverable error occurred |+| `ERR_MOCHA_FORBIDDEN_EXCLUSIVITY` | `.only()` was used with `--forbid-only` |+| `ERR_MOCHA_INSTANCE_ALREADY_DISPOSED` | `run()` was called on a Mocha instance that has already been disposed |+| `ERR_MOCHA_INSTANCE_ALREADY_RUNNING` | `run()` was called on a Mocha instance that is already running |+| `ERR_MOCHA_INVALID_ARG_TYPE` | wrong type was passed for a given argument |+| `ERR_MOCHA_INVALID_ARG_VALUE` | invalid or unsupported value was passed for a given argument |+| `ERR_MOCHA_INVALID_EXCEPTION` | a falsy or otherwise underspecified exception was thrown |+| `ERR_MOCHA_INVALID_INTERFACE` | interface specified in options not found |+| `ERR_MOCHA_INVALID_PLUGIN_DEFINITION` | a plugin definition (e.g., `mochaHooks`) was invalid |+| `ERR_MOCHA_INVALID_PLUGIN_IMPLEMENTATION` | a user-supplied plugin implementation was invalid |+| `ERR_MOCHA_INVALID_REPORTER` | reporter specified in options not found |+| `ERR_MOCHA_MULTIPLE_DONE` | `done()` was called multiple times in a test or hook |+| `ERR_MOCHA_NO_FILES_MATCH_PATTERN` | test file(s) could not be found |+| `ERR_MOCHA_TIMEOUT` | a test or hook exceeded its allowed run time |+| `ERR_MOCHA_UNPARSABLE_FILE` | a configuration or test file could not be parsed |+| `ERR_MOCHA_UNSUPPORTED` | requested behavior, option, or parameter is unsupported |diff --git a/docs/src/content/docs/running/cli.mdx b/docs/src/content/docs/running/cli.mdxindex 3978fff3..4bf2443f 100644--- a/docs/src/content/docs/running/cli.mdx+++ b/docs/src/content/docs/running/cli.mdx@@ -397,10 +397,10 @@ By default, Mocha looks for a `package.json` in the current working directory or### `--extension <ext>`Files having this extension will be considered test files.-Defaults to `js`.+Defaults to `js`, `cjs`, and `mjs`.-Specifying `--extension` will _remove_ `.js` as a test file extension; use `--extension js` to re-add it.-For example, to load `.mjs` and `.js` test files, you must supply `--extension mjs --extension js`.+Specifying `--extension` will _remove_ the default extensions; use `--extension js` to re-add it.+For example, to load `.ts` and `.js` test files, you must supply `--extension ts --extension js`.The option can be given multiple times.The option accepts a comma-delimited list: `--extension a,b` is equivalent to `--extension a --extension b`.diff --git a/docs/src/content/docs/running/configuring.mdx b/docs/src/content/docs/running/configuring.mdxindex 94f64783..54739352 100644--- a/docs/src/content/docs/running/configuring.mdx+++ b/docs/src/content/docs/running/configuring.mdx@@ -37,7 +37,9 @@ Likewise, use `--no-package` to stop Mocha from looking for configuration in a `If no custom path was given, and if there are multiple configuration files in the same directory, Mocha will search for--and use--only one.The priority is:+1. `.mocharc.cjs`1. `.mocharc.js`+1. `.mocharc.mjs`1. `.mocharc.yaml`1. `.mocharc.yml`1. `.mocharc.jsonc`