☕️ Classic, reliable, trusted test framework for Node.js and the browser
chore: rewrite base path instead of copy-pasting (#5431)
Mark Wiemerc6c6740fb45d
diff --git a/docs-next/astro.config.ts b/docs-next/astro.config.tsindex a770c660..bcef0fa2 100644--- a/docs-next/astro.config.ts+++ b/docs-next/astro.config.ts@@ -1,8 +1,22 @@import { defineConfig } from "astro/config";import starlight from "@astrojs/starlight";+import { visit } from "unist-util-visit";++const base = "/next";++/** Prepend base URL to non-`/api` absolute links */+const rewriteLinks = ({ base }: { base: string }) => {+ return (tree: any) => {+ visit(tree, "link", (node) => {+ if (node.url.startsWith("/") && !node.url.startsWith("/api")) {+ node.url = base + node.url;+ }+ });+ };+};export default defineConfig({- base: "/next",+ base,integrations: [starlight({components: {@@ -146,4 +160,7 @@ export default defineConfig({title: "Mocha",}),],+ markdown: {+ remarkPlugins: [[rewriteLinks, { base }]],+ },});diff --git a/docs-next/package-lock.json b/docs-next/package-lock.jsonindex 4eb347f2..b861116e 100644--- a/docs-next/package-lock.json+++ b/docs-next/package-lock.json@@ -16,7 +16,8 @@"needle": "^3.3.1","sharp": "^0.32.5","starlight-package-managers": "^0.7.0",- "typescript": "^5.6.3"+ "typescript": "^5.6.3",+ "unist-util-visit": "^5.0.0"}},"node_modules/@ampproject/remapping": {@@ -6281,23 +6282,6 @@"node": ">=18.12"}},- "node_modules/prettier": {- "version": "3.3.3",- "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.3.3.tgz",- "integrity": "sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew==",- "license": "MIT",- "optional": true,- "peer": true,- "bin": {- "prettier": "bin/prettier.cjs"- },- "engines": {- "node": ">=14"- },- "funding": {- "url": "https://github.com/prettier/prettier?sponsor=1"- }- },"node_modules/prismjs": {"version": "1.29.0","resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.29.0.tgz",diff --git a/docs-next/package.json b/docs-next/package.jsonindex 99f020d2..613a9e0c 100644--- a/docs-next/package.json+++ b/docs-next/package.json@@ -3,14 +3,14 @@"type": "module","version": "0.0.1","scripts": {- "generate": "node ../docs/_data/supporters.js --write-supporters-json",+ "astro": "astro",+ "build": "astro check && astro build",+ "build-with-old": "npm run generate && npm run build -- --outDir ../docs/_site/next","dev": "astro dev",- "start": "astro dev","docs": "cd .. && npm i && cd docs-next && npm run generate && npm run build",- "build": "astro check && astro build",+ "generate": "node ../docs/_data/supporters.js --write-supporters-json","preview": "astro preview",- "build-with-old": "npm run generate && npm run build -- --outDir ../docs/_site/next",- "astro": "astro"+ "start": "astro dev"},"dependencies": {"@astrojs/check": "^0.9.4",@@ -21,6 +21,7 @@"needle": "^3.3.1","sharp": "^0.32.5","starlight-package-managers": "^0.7.0",- "typescript": "^5.6.3"+ "typescript": "^5.6.3",+ "unist-util-visit": "^5.0.0"}}diff --git a/docs-next/src/content/docs/declaring/dynamic-tests.mdx b/docs-next/src/content/docs/declaring/dynamic-tests.mdxindex 85fdf8df..b2921727 100644--- a/docs-next/src/content/docs/declaring/dynamic-tests.mdx+++ b/docs-next/src/content/docs/declaring/dynamic-tests.mdx@@ -62,7 +62,7 @@ describe("add()", function () {With `top-level await` you can collect your test data in a dynamic and asynchronous way while the test file is being loaded.-See also [`--delay`](/next/features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.+See also [`--delay`](/features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.```js// testfile.mjsdiff --git a/docs-next/src/content/docs/declaring/exclusive-tests.mdx b/docs-next/src/content/docs/declaring/exclusive-tests.mdxindex 6ee3d1ed..1499ccdc 100644--- a/docs-next/src/content/docs/declaring/exclusive-tests.mdx+++ b/docs-next/src/content/docs/declaring/exclusive-tests.mdx@@ -4,7 +4,7 @@ title: Exclusive Tests---:::caution-Exclusive tests are incompatible with [parallel mode](/next/features/parallel-mode).+Exclusive tests are incompatible with [parallel mode](/features/parallel-mode).:::The exclusivity feature allows you to run _only_ the specified suite or test-casediff --git a/docs-next/src/content/docs/declaring/inclusive-tests.mdx b/docs-next/src/content/docs/declaring/inclusive-tests.mdxindex 987dbaab..1797eb4e 100644--- a/docs-next/src/content/docs/declaring/inclusive-tests.mdx+++ b/docs-next/src/content/docs/declaring/inclusive-tests.mdx@@ -5,7 +5,7 @@ title: Inclusive TestsThis feature is the inverse of `.only()`.By appending `.skip()`, you may tell Mocha to ignore test case(s).-Anything skipped will be marked as [pending](/next/declaring/pending-tests) and reported as such.+Anything skipped will be marked as [pending](/declaring/pending-tests) and reported as such.Here's an example of skipping an individual test:```js@@ -56,7 +56,7 @@ it('should only test in the correct environment', function() {});```-The above test will be reported as [pending](/next/declaring/pending-tests).+The above test will be reported as [pending](/declaring/pending-tests).It's also important to note that calling `this.skip()` will effectively _abort_ the test.:::tip[Best practice]diff --git a/docs-next/src/content/docs/declaring/pending-tests.mdx b/docs-next/src/content/docs/declaring/pending-tests.mdxindex 0bc75d85..efed82f3 100644--- a/docs-next/src/content/docs/declaring/pending-tests.mdx+++ b/docs-next/src/content/docs/declaring/pending-tests.mdx@@ -17,4 +17,4 @@ describe("Array", function () {Pending tests will be included in the test results and marked as pending.A pending test is not considered a failed test.-Read the [inclusive tests section](/next/declaring/inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.+Read the [inclusive tests section](/declaring/inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.diff --git a/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdx b/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdxindex 0661e9c3..bc4f6125 100644--- a/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdx+++ b/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdx@@ -26,9 +26,9 @@ More information can be found in the [Node.js documentation](https://nodejs.org/### Current Limitations-- [Watch mode](/next/running/cli#--watch--w) does not support ES Module test files-- [Custom reporters](/next/reporters/third-party) and [custom interfaces](/next/interfaces/third-party) can only be CommonJS files-- [Configuration file](/next/running/configuring) can only be a CommonJS file (`.mocharc.js` or `.mocharc.cjs`)+- [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-next/src/content/docs/explainers/run-cycle-overview.mdx b/docs-next/src/content/docs/explainers/run-cycle-overview.mdxindex f5c70d02..65e3648a 100644--- a/docs-next/src/content/docs/explainers/run-cycle-overview.mdx+++ b/docs-next/src/content/docs/explainers/run-cycle-overview.mdx@@ -11,35 +11,35 @@ In a browser, test files are loaded by `<script>` tags, and calling `mocha.run()1. User (that's you) executes `mocha`2. Loads options from config files, if present-3. Mocha processes any command-line options provided (see section on [configuration merging](/next/running/configuring#merging) for details)+3. Mocha processes any command-line options provided (see section on [configuration merging](/running/configuring#merging) for details)4. If known flags for the `node` executable are found:1. Mocha will spawn `node` in a child process, executing itself with these flags2. Otherwise, Mocha does not spawn a child process5. Mocha loads modules specified by `--require`- 1. If a file loaded this way contains known Mocha-specific exports (e.g., [root hook plugins](/next/features/root-hook-plugins)), Mocha "registers" these+ 1. If a file loaded this way contains known Mocha-specific exports (e.g., [root hook plugins](/features/root-hook-plugins)), Mocha "registers" these2. If not, Mocha ignores any exports of a `--require`'d module6. Mocha validates any custom reporters or interfaces which were loaded via `--require` or otherwise7. Mocha _discovers_ test files; when given no files or directories, it finds files with extensions `.js`, `.mjs` or `.cjs` in the `test` directory (but not its children), relative to the current working directory-8. The (default) [bdd interface](/next/interfaces/bdd) loads the test files _in no particular order_, which are given an interface-specific `global` context (this is how, e.g., `describe()` ends up as a global in a test file)+8. The (default) [bdd interface](/interfaces/bdd) loads the test files _in no particular order_, which are given an interface-specific `global` context (this is how, e.g., `describe()` ends up as a global in a test file)1. When a test file is loaded, Mocha executes all of its suites and finds--_but does not execute_--any hooks and tests therein.2. Top-level hooks, tests and suites are all made members of an "invisible" _root suite_; there is only _one_ root suite for the entire process-9. Mocha runs [global setup fixtures](/next/features/global-fixtures#global-setup-fixtures), if any+9. Mocha runs [global setup fixtures](/features/global-fixtures#global-setup-fixtures), if any10. Starting with the "root" suite, Mocha executes:-11. Any "before all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/features/root-hook-plugins))+11. Any "before all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/features/root-hook-plugins))12. For each test, Mocha executes:1. Any "before each" hooks2. The test (and reports the result)3. Any "after each" hooks13. If the current suite has a child suite, repeat the steps in 10. for each child suite; each child suite _inherits_ any "before each" and "after each" hooks defined in its parent-14. Any "after all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/features/root-hook-plugins))+14. Any "after all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/features/root-hook-plugins))15. Mocha prints a final summary/epilog, if applicable-16. Mocha runs [global teardown fixtures](/next/features/global-fixtures#global-teardown-fixtures), if any+16. Mocha runs [global teardown fixtures](/features/global-fixtures#global-teardown-fixtures), if any## Parallel Mode1. Repeat steps 1 through 6 from [Serial Mode](#serial-mode) above, skipping reporter validation2. All test files found are put into a queue (they are _not_ loaded by the main process)-3. Mocha runs [global setup fixtures](/next/features/global-fixtures#global-setup-fixtures), if any+3. Mocha runs [global setup fixtures](/features/global-fixtures#global-setup-fixtures), if any4. Mocha creates a pool of subprocesses ("workers")5. _Immediately before_ a worker runs the first test it receives, the worker "bootstraps" itself by:1. Loading all `--require`'d modules@@ -52,4 +52,4 @@ In a browser, test files are loaded by `<script>` tags, and calling `mocha.run()9. When the worker completes the test file, buffered results are returned to the main process, which then gives them to the user-specified reporter (`spec` by default)10. The worker makes itself available to the pool; the pool gives the worker another test file to run, if any remain11. Mocha prints a final summary/epilog, if applicable-12. Mocha runs [global teardown fixtures](/next/features/global-fixtures#global-teardown-fixtures), if any+12. Mocha runs [global teardown fixtures](/features/global-fixtures#global-teardown-fixtures), if anydiff --git a/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx b/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdxindex 5a926c72..bfee7a5b 100644--- a/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx+++ b/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx@@ -3,7 +3,7 @@ description: Helping you decide which API(s) to use for your test fixtures.title: Test Fixture Decision Tree----This flowchart will help you decide when to use [hooks](/next/features/hooks), [root hook plugins](/next/features/root-hook-plugins) or [global fixtures](/next/features/global-fixtures).+This flowchart will help you decide when to use [hooks](/features/hooks), [root hook plugins](/features/root-hook-plugins) or [global fixtures](/features/global-fixtures).import FixtureWizard from "../../../components/FixtureWizard.astro";diff --git a/docs-next/src/content/docs/features/global-fixtures.mdx b/docs-next/src/content/docs/features/global-fixtures.mdxindex 44d96b0a..bed58dba 100644--- a/docs-next/src/content/docs/features/global-fixtures.mdx+++ b/docs-next/src/content/docs/features/global-fixtures.mdx@@ -6,7 +6,7 @@ title: Global Fixtures:::note[New in v8.2.0]:::-At first glance, _global fixtures_ seem similar to [root hook plugins](/next/features/root-hook-plugins).+At first glance, _global fixtures_ seem similar to [root hook plugins](/features/root-hook-plugins).However, unlike root hooks, global fixtures:1. Are _guaranteed_ to execute _once and only once_@@ -44,7 +44,7 @@ export async function mochaGlobalSetup() {To use it, load this file when running Mocha via `mocha --require fixtures.cjs` (or whatever you have named the file).:::tip-Remember: you can define "requires" in a [configuration file](/next/running/configuring).+Remember: you can define "requires" in a [configuration file](/running/configuring).:::Now, before Mocha loads and runs your tests, it will execute the above global setup fixture, starting a server for testing.@@ -96,7 +96,7 @@ You could be clever and try to get around this restriction by assigning somethinIt's probably best to play by the rules!:::-Instead, use the global fixture to _start_ the database, and use [root hook plugins](/next/features/root-hook-plugins) or plain old [hooks](/next/features/hooks) to create a connection.+Instead, use the global fixture to _start_ the database, and use [root hook plugins](/features/root-hook-plugins) or plain old [hooks](/features/hooks) to create a connection.Here's an example of using global fixtures and "before all" hooks to get the job done.Note that we do not reference the `server` object anywhere in our tests!diff --git a/docs-next/src/content/docs/features/hooks.mdx b/docs-next/src/content/docs/features/hooks.mdxindex 13f63588..2053a4b1 100644--- a/docs-next/src/content/docs/features/hooks.mdx+++ b/docs-next/src/content/docs/features/hooks.mdx@@ -87,12 +87,12 @@ describe("Connection", function () {A hook defined at the top scope of a test file (outside of a suite) is a _root hook_.-As of v8.0.0, [Root Hook Plugins](/next/features/root-hook-plugins) are the preferred mechanism for setting root hooks.+As of v8.0.0, [Root Hook Plugins](/features/root-hook-plugins) are the preferred mechanism for setting root hooks.## Delayed Root Suite:::caution-Delayed root suites are incompatible with [parallel mode](/next/features/parallel-mode).+Delayed root suites are incompatible with [parallel mode](/features/parallel-mode).:::If you need to perform asynchronous operations before any of your suites are run (e.g. for dynamically generating tests), you may delay the root suite.diff --git a/docs-next/src/content/docs/features/parallel-mode.mdx b/docs-next/src/content/docs/features/parallel-mode.mdxindex c0015ff7..cbee8bd2 100644--- a/docs-next/src/content/docs/features/parallel-mode.mdx+++ b/docs-next/src/content/docs/features/parallel-mode.mdx@@ -6,7 +6,7 @@ title: Parallel Mode:::note[New in v8.0.0]:::-Depending on the number and nature of your tests, you may find a significant performance benefit when running tests in parallel (using the [`--parallel`](/next/running/cli#--parallel--p) flag).+Depending on the number and nature of your tests, you may find a significant performance benefit when running tests in parallel (using the [`--parallel`](/running/cli#--parallel--p) flag).Parallel tests should work out-of-the box for many use cases.However, you must be aware of some important implications of the behavior.@@ -19,9 +19,9 @@ Authors of third-party libraries built on Mocha should read this!Due to the nature of the following reporters, they cannot work when running tests in parallel:-- [`json-stream`](/next/reporters/json-stream)-- [`markdown`](/next/reporters/markdown)-- [`progress`](/next/reporters/progress)+- [`json-stream`](/reporters/json-stream)+- [`markdown`](/reporters/markdown)+- [`progress`](/reporters/progress)These reporters expect Mocha to know _how many tests it plans to run_ before execution.This information is unavailable in parallel mode, as test files are loaded only when they are about to be run.@@ -38,7 +38,7 @@ This is for the same reason as the incompatible reporters noted above: in parallSuggested workarounds:-1. Use [`--grep`](/next/running/cli#--grep-regexp--g-regexp) or [`--fgrep`](/next/running/cli#--fgrep-string--f-string) instead; it's not particularly efficient, but it will work.+1. Use [`--grep`](/running/cli#--grep-regexp--g-regexp) or [`--fgrep`](/running/cli#--fgrep-string--f-string) instead; it's not particularly efficient, but it will work.1. Don't use parallel mode.Likely, you won't be running very many exclusive tests, so you won't see a great benefit from parallel mode anyhow.@@ -52,15 +52,15 @@ In parallel mode, Mocha does not guarantee the order in which test files will ruBecause of this, the following options, which depend on order, _cannot be used_ in parallel mode:-- [`--file`](/next/running/cli#--file-file)-- [`--sort`](/next/running/cli#--sort--s)-- [`--delay`](/next/running/cli#--delay)+- [`--file`](/running/cli#--file-file)+- [`--sort`](/running/cli#--sort--s)+- [`--delay`](/running/cli#--delay)## Test Duration VariabilityRunning tests in parallel mode will naturally use more system resources.The OS may take extra time to schedule and complete some operations, depending on system load.-For this reason, the timeouts of _individual tests_ may need to be increased either [globally](/next/running/cli#--timeout-ms--t-ms) or [otherwise](/next/features/timeouts).+For this reason, the timeouts of _individual tests_ may need to be increased either [globally](/running/cli#--timeout-ms--t-ms) or [otherwise](/features/timeouts).## "Bail" is "Best Effort"@@ -112,9 +112,9 @@ Here are a couple suggested workarounds:1. `require('./setup.js')` or `import './setup.js'` at the top of every test file.Best avoided for those averse to boilerplate.-1. _Recommended_: Define root hooks in a "required" file, using the [Root Hook Plugin](/next/features/root-hook-plugins) system.+1. _Recommended_: Define root hooks in a "required" file, using the [Root Hook Plugin](/features/root-hook-plugins) system.-If you need to run some code _once and only once_, use a [global fixture](/next/features/global-fixtures) instead.+If you need to run some code _once and only once_, use a [global fixture](/features/global-fixtures) instead.## No Browser Support@@ -127,15 +127,15 @@ If a third-party reporter does not work in parallel mode (but otherwise works in## Troubleshooting Parallel Mode-If you find your tests don't work properly when run with [`--parallel`](/next/running/cli#--parallel--p), either shrug and move on, or use this handy-dandy checklist to get things working:+If you find your tests don't work properly when run with [`--parallel`](/running/cli#--parallel--p), either shrug and move on, or use this handy-dandy checklist to get things working:- ✅ Ensure you are using a [supported reporter](#reporter-limitations).- ✅ Ensure you are not using [other unsupported flags](#file-order-is-non-deterministic).-- ✅ Double-check your [config file](/next/running/configuring); options set in config files will be merged with any command-line option.+- ✅ Double-check your [config file](/running/configuring); options set in config files will be merged with any command-line option.- ✅ Look for [root hooks](#root-hooks-are-not-global) in your tests.- Move them into a [Root Hook Plugin](/next/features/root-hook-plugins).+ Move them into a [Root Hook Plugin](/features/root-hook-plugins).- ✅ Do any assertion, mock, or other test libraries you're consuming use root hooks? They may need to be [migrated](#migrating-a-library-to-use-root-hook-plugins) for compatibility with parallel mode.-- ✅ If tests are unexpectedly timing out, you may need to increase the default test timeout (via [`--timeout`](/next/running/cli#--timeout-ms--t-ms))+- ✅ If tests are unexpectedly timing out, you may need to increase the default test timeout (via [`--timeout`](/running/cli#--timeout-ms--t-ms))- ✅ Ensure your tests do not depend on being run in a specific order.- ✅ Ensure your tests clean up after themselves; remove temp files, handles, sockets, etc.Don't try to share state or resources between test files.@@ -149,7 +149,7 @@ Free-tier cloud CI services may not provide a suitable multi-core container or VRegarding expected performance gains in CI: your mileage may vary.It may help to use a conditional in a `.mocharc.js` to check for `process.env.CI`, and adjust the job count as appropriate.-It's unlikely (but not impossible) to see a performance gain from a [job count](/next/running/cli#--jobs-count--j-count) _greater than_ the number of available CPU cores.+It's unlikely (but not impossible) to see a performance gain from a [job count](/running/cli#--jobs-count--j-count) _greater than_ the number of available CPU cores.That said, _play around with the job count_--there's no one-size-fits all, and the unique characteristics of your tests will determine the optimal number of jobs; it may even be that fewer is faster!## Parallel Mode Worker IDsdiff --git a/docs-next/src/content/docs/features/root-hook-plugins.mdx b/docs-next/src/content/docs/features/root-hook-plugins.mdxindex 4a22997d..824e5db2 100644--- a/docs-next/src/content/docs/features/root-hook-plugins.mdx+++ b/docs-next/src/content/docs/features/root-hook-plugins.mdx@@ -6,15 +6,15 @@ title: Root Hook Plugins:::note[New in v8.0.0]:::-In some cases, you may want a [hook](/next/features/hooks) before (or after) every test in every file.+In some cases, you may want a [hook](/features/hooks) before (or after) every test in every file.These are called _root hooks_.-Previous to v8.0.0, the way to accomplish this was to use `--file` combined with root hooks (see _[Root Hooks Are Not Global](/next/features/parallel-mode#root-hooks-are-not-global)_).+Previous to v8.0.0, the way to accomplish this was to use `--file` combined with root hooks (see _[Root Hooks Are Not Global](/features/parallel-mode#root-hooks-are-not-global)_).This still works in v8.0.0, but _not_ when running tests in parallel mode!For that reason, running root hooks using this method is _strongly discouraged_, and may be deprecated in the future.-A _Root Hook Plugin_ is a JavaScript file loaded via [`--require`](/next/running/cli#--require-module--r-module) which "registers" one or more root hooks to be used across all test files.+A _Root Hook Plugin_ is a JavaScript file loaded via [`--require`](/running/cli#--require-module--r-module) which "registers" one or more root hooks to be used across all test files.-In browsers you can set root hooks directly via a `rootHooks` object: `mocha.setup({ rootHooks: { beforeEach() {...} } })`, see [`mocha.setup()`](/next/running/browsers)+In browsers you can set root hooks directly via a `rootHooks` object: `mocha.setup({ rootHooks: { beforeEach() {...} } })`, see [`mocha.setup()`](/running/browsers)## Defining a Root Hook Plugin@@ -78,7 +78,7 @@ Available root hooks and their behavior:- In **both** modes, run _after every test_:::tip-If you need to ensure code runs once and only once in any mode, use [global fixtures](/next/features/global-fixtures).+If you need to ensure code runs once and only once in any mode, use [global fixtures](/features/global-fixtures).:::As with other hooks, `this` refers to the current context object:@@ -180,7 +180,7 @@ To migrate your tests using root hooks to a root hook plugin:1. Create a new file, e.g., `test/hooks.js`.1. _Move_ your root hooks into `test/hooks.js`.1. In `test/hooks.js`, make your hooks a member of an exported `mochaHooks` property.-1. Use `--require test/hooks.js` (even better: use a [config file](/next/running/configuring) with `{"require": "test/hooks.js"}`) when running your tests.+1. Use `--require test/hooks.js` (even better: use a [config file](/running/configuring) with `{"require": "test/hooks.js"}`) when running your tests.For example, given the following file, `test/test.spec.js`, containing root hooks:@@ -234,7 +234,7 @@ describe("my test suite", function () {});```-Running `mocha --require test/hooks.js test/test.spec.js` will run as before (and is now ready to be used with [`--parallel`](/next/running/cli#--parallel--p)).+Running `mocha --require test/hooks.js test/test.spec.js` will run as before (and is now ready to be used with [`--parallel`](/running/cli#--parallel--p)).## Migrating a Library to use Root Hook PLuginsdiff --git a/docs-next/src/content/docs/getting-started.mdx b/docs-next/src/content/docs/getting-started.mdxindex 84fedf6e..8ee57eb4 100644--- a/docs-next/src/content/docs/getting-started.mdx+++ b/docs-next/src/content/docs/getting-started.mdx@@ -71,9 +71,9 @@ You can then run that script with your favorite package manager:See:-- [CLI](/next/running/cli) for the commands you can pass to `mocha`-- [Configuring](/next/running/configuring) for creating a persistent test configuration file-- [Editor Plugins](/next/running/editor-plugins) for improving the Mocha experience in your editor+- [CLI](/running/cli) for the commands you can pass to `mocha`+- [Configuring](/running/configuring) for creating a persistent test configuration file+- [Editor Plugins](/running/editor-plugins) for improving the Mocha experience in your editorYou can see real live example code in our example repositories:diff --git a/docs-next/src/content/docs/running/browsers.mdx b/docs-next/src/content/docs/running/browsers.mdxindex 4f08f403..4f41957d 100644--- a/docs-next/src/content/docs/running/browsers.mdx+++ b/docs-next/src/content/docs/running/browsers.mdx@@ -86,17 +86,17 @@ mocha.setup({## Browser-Specific Options-Browser Mocha supports many, but not all [CLI options](/next/running/configuring).+Browser Mocha supports many, but not all [CLI options](/running/configuring).To use a CLI option that contains a "-", please convert the option to camelCase, (eg. `check-leaks` to `checkLeaks`).-### Options That Differ Slightly From [CLI Options](/next/running/configuring)+### Options That Differ Slightly From [CLI Options](/running/configuring)> `reporter` _`string|constructor`_You can pass a reporter's name or a custom reporter's constructor.You can find **recommended** reporters for the browser [here](#reporting).-It is possible to use [built-in reporters](/next/reporters/spec) as well.+It is possible to use [built-in reporters](/reporters/spec) as well.Their employment in browsers is neither recommended nor supported, open the console to see the test results.### Options That _Only_ Function In Browser Contextdiff --git a/docs-next/src/content/docs/running/cli.mdx b/docs-next/src/content/docs/running/cli.mdxindex 79ebba50..aa192142 100644--- a/docs-next/src/content/docs/running/cli.mdx+++ b/docs-next/src/content/docs/running/cli.mdx@@ -140,7 +140,7 @@ See [further explanation and workarounds](https://github.com/mochajs/mocha/wiki/Delay initial execution of root suite.-See [Delayed Root Suite](/next/features/hooks#delayed-root-suite).+See [Delayed Root Suite](/features/hooks#delayed-root-suite).### `--dry-run`@@ -172,7 +172,7 @@ To ensure your tests aren't leaving messes around, here are some ideas to get st- See the [Node.js guide to debugging](https://nodejs.org/en/docs/inspector)- Use the new [`async_hooks`](https://github.com/nodejs/node/blob/master/doc/api/async_hooks.md) API ([example](https://gist.github.com/boneskull/7fe75b63d613fa940db7ec990a5f5843))- Try something like [wtfnode](https://npm.im/wtfnode)-- Use [`.only`](/next/declaring/exclusive-tests) until you find the test that causes Mocha to hang+- Use [`.only`](/declaring/exclusive-tests) until you find the test that causes Mocha to hang### `--pass-on-failing-test-suite`@@ -243,7 +243,7 @@ Each test file will be put into a queue and executed as workers become available:::caution`--parallel` has certain implications for Mocha's behavior which you must be aware of.-Read more about [running tests in parallel](/next/features/parallel-mode).+Read more about [running tests in parallel](/features/parallel-mode).:::### `--retries <n>`@@ -361,7 +361,7 @@ Can be specified as a comma-delimited list.:::note[New in v6.0.0]:::-Specify an explicit path to a [configuration file](/next/running/configuring).+Specify an explicit path to a [configuration file](/running/configuring).By default, Mocha will search for a config file if `--config` is not specified; use `--no-config` to suppress this behavior.@@ -380,7 +380,7 @@ Can also be specified as a comma-delimited list: `-n require=foo,unhandled-rejec### `--opts <path>`:::note[Removed in v8.0.0]-Please use [configuration file](/next/running/configuring) instead.+Please use [configuration file](/running/configuring) instead.:::### `--package <path>`@@ -388,7 +388,7 @@ Please use [configuration file](/next/running/configuring) instead.:::note[New in v6.0.0]:::-Specify an explicit path to a [`package.json` file](/next/running/configuring) (ostensibly containing configuration in a `mocha` property).+Specify an explicit path to a [`package.json` file](/running/configuring) (ostensibly containing configuration in a `mocha` property).By default, Mocha looks for a `package.json` in the current working directory or nearest ancestor, and will use the first file found (regardless of whether it contains a `mocha` property); to suppress `package.json` lookup, use `--no-package`.@@ -413,7 +413,7 @@ The option accepts a comma-delimited list: `--extension a,b` is equivalent to `-### `--file <file>`:::caution-`--file` is incompatible with [parallel mode](/next/features/parallel-mode).+`--file` is incompatible with [parallel mode](/features/parallel-mode).:::Explicitly _include_ a test file to be loaded before other test files.@@ -458,18 +458,18 @@ Modules required in this manner are expected to do work synchronously; Mocha won:::caution**You cannot use `--require` to set hooks**.-If you want to set hooks to run, e.g., before each test, use a [Root Hook Plugin](/next/features/root-hook-plugins).+If you want to set hooks to run, e.g., before each test, use a [Root Hook Plugin](/features/root-hook-plugins).::::::note-As of v8.0.0, Mocha supports `--require` for [NodeJS native ESM](/next/explainers/nodejs-native-esm-support).+As of v8.0.0, Mocha supports `--require` for [NodeJS native ESM](/explainers/nodejs-native-esm-support).There is no separate `--import` flag.:::### `--sort, -S`:::caution-`--sort` is incompatible with [parallel mode](/next/features/parallel-mode).+`--sort` is incompatible with [parallel mode](/features/parallel-mode).:::Sort test files (by absolute path) using [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).@@ -596,7 +596,7 @@ The `mocha` executable supports all applicable flags which the `node` executableThese flags vary depending on your version of Node.js.-`node` flags can be defined in Mocha's [configuration](/next/running/configuring).+`node` flags can be defined in Mocha's [configuration](/running/configuring).:::note[New in v9.1.0]You can also pass `node` flags to Node.js using [`--node-option`](#--node-option-name--n-name).@@ -620,7 +620,7 @@ Error: coolPrepend `--v8-` to any flag listed in the output of `node --v8-options` (excluding `--v8-options` itself) to use it.-[V8](https://v8.dev/) flags can be defined in Mocha's [configuration](/next/running/configuring).+[V8](https://v8.dev/) flags can be defined in Mocha's [configuration](/running/configuring).:::note[New in v9.1.0]You can also pass V8 flags (without `--v8-`) to Node.js using [`--node-option`](#--node-option-name--n-name).diff --git a/docs-next/src/content/docs/running/configuring.mdx b/docs-next/src/content/docs/running/configuring.mdxindex bfe3403d..64f80525 100644--- a/docs-next/src/content/docs/running/configuring.mdx+++ b/docs-next/src/content/docs/running/configuring.mdx@@ -8,7 +8,7 @@ title: Configuring Mocha (Node.js)Mocha supports configuration files, typical of modern command-line tools, in several formats:-- **JavaScript**: Create a `.mocharc.js` (or `.mocharc.cjs` when using [`"type"="module"`](/next/explainers/nodejs-native-esm-support) in your `package.json`)+- **JavaScript**: Create a `.mocharc.js` (or `.mocharc.cjs` when using [`"type"="module"`](/explainers/nodejs-native-esm-support) in your `package.json`)in your project's root directory, and export an object (`module.exports = {/* ... */}`) containing your configuration.- **YAML**: Create a `.mocharc.yaml` (or `.mocharc.yml`) in your project's root directory.- **JSON**: Create a `.mocharc.json` (or `.mocharc.jsonc`) in your project's root directory.