Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ 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.ts
index 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.json
index 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.json
index 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.mdx
index 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.mjs
diff --git a/docs-next/src/content/docs/declaring/exclusive-tests.mdx b/docs-next/src/content/docs/declaring/exclusive-tests.mdx
index 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-case
diff --git a/docs-next/src/content/docs/declaring/inclusive-tests.mdx b/docs-next/src/content/docs/declaring/inclusive-tests.mdx
index 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 Tests
This 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.mdx
index 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.mdx
index 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.mdx
index 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 flags
2. Otherwise, Mocha does not spawn a child process
5. 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" these
2. If not, Mocha ignores any exports of a `--require`'d module
6. Mocha validates any custom reporters or interfaces which were loaded via `--require` or otherwise
7. 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 any
10. 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" hooks
2. The test (and reports the result)
3. Any "after each" hooks
13. 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 Mode
1. Repeat steps 1 through 6 from [Serial Mode](#serial-mode) above, skipping reporter validation
2. 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 any
4. 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 remain
11. 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 any
diff --git a/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx b/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx
index 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.mdx
index 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 somethin
It'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.mdx
index 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.mdx
index 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 parall
Suggested 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 ru
Because 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 Variability
Running 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 V
Regarding 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 IDs
diff --git a/docs-next/src/content/docs/features/root-hook-plugins.mdx b/docs-next/src/content/docs/features/root-hook-plugins.mdx
index 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 PLugins
diff --git a/docs-next/src/content/docs/getting-started.mdx b/docs-next/src/content/docs/getting-started.mdx
index 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 editor
You 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.mdx
index 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 Context
diff --git a/docs-next/src/content/docs/running/cli.mdx b/docs-next/src/content/docs/running/cli.mdx
index 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` executable
These 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: cool
Prepend `--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.mdx
index 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.