Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ 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.mdx
index 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 ./test
diff --git a/docs/src/content/docs/explainers/nodejs-native-esm-support.mdx b/docs/src/content/docs/explainers/nodejs-native-esm-support.mdx
index 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.mdx
index 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` pr
Where 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.mdx
index 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.mdx
index 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`