Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ Classic, reliable, trusted test framework for Node.js and the browser

docs: fix links in new site (#5416)

Mark Wiemerb2bc769c6c8d
diff --git a/docs-next/README.md b/docs-next/README.md
index 7ef2c817..c6330c35 100644
--- a/docs-next/README.md
+++ b/docs-next/README.md
@@ -1,25 +1,14 @@
-# Mocha Docs vNext: Built on Astro Starlight
+# Mocha Docs: Built on Astro Starlight
-After `cd`ing into this directory:
+This is the new site, hosted at https://mochajs.org/next and built with [Astro Starlight](https://starlight.astro.build). For details on how to build alongside the old site, see the `docs` directory.
+
+To run this site alone:
```shell
+cd docs-next
npm i
npm run generate
npm run dev
```
-To merge with the old site:
-
-```shell
-npm i
-npm run build-with-old
-```
-
-To preview the old and new site:
-
-```shell
-cd .. # back to root dir
-npm run docs:preview
-```
-
-The new site will be at `http://localhost:8080/next`
+However, note that relative links may resolve with `dev` but fail with `build` and `preview` (see https://github.com/mochajs/mocha/issues/5415).
diff --git a/docs-next/src/content/docs/declaring/dynamic-tests.mdx b/docs-next/src/content/docs/declaring/dynamic-tests.mdx
index 08b7425b..85fdf8df 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`](../features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.
+See also [`--delay`](/next/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 6a480bb6..6ee3d1ed 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](../features/parallel-mode).
+Exclusive tests are incompatible with [parallel mode](/next/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 056583be..987dbaab 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](./pending-tests) and reported as such.
+Anything skipped will be marked as [pending](/next/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](./pending-tests).
+The above test will be reported as [pending](/next/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 fbd0ac4a..0bc75d85 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](./inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.
+Read the [inclusive tests section](/next/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 d2e1e97a..0661e9c3 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](../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`)
+- [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`)
- 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 959c86f9..f5c70d02 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](../running/configuring#merging) for details)
+3. Mocha processes any command-line options provided (see section on [configuration merging](/next/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](../features/root-hook-plugins)), Mocha "registers" these
+ 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
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](../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](/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)
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](../features/global-fixtures#global-setup-fixtures), if any
+9. Mocha runs [global setup fixtures](/next/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](../features/root-hook-plugins))
+11. Any "before all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/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](../features/root-hook-plugins))
+14. Any "after all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/features/root-hook-plugins))
15. Mocha prints a final summary/epilog, if applicable
-16. Mocha runs [global teardown fixtures](../features/global-fixtures#global-teardown-fixtures), if any
+16. Mocha runs [global teardown fixtures](/next/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](../features/global-fixtures#global-setup-fixtures), if any
+3. Mocha runs [global setup fixtures](/next/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](../features/global-fixtures#global-teardown-fixtures), if any
+12. Mocha runs [global teardown fixtures](/next/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 82c9ee20..5a926c72 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](../features/hooks), [root hook plugins](../features/root-hook-plugins) or [global fixtures](../features/global-fixtures).
+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).
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 bb4320c1..44d96b0a 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](./root-hook-plugins).
+At first glance, _global fixtures_ seem similar to [root hook plugins](/next/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](../running/configuring).
+Remember: you can define "requires" in a [configuration file](/next/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](./root-hook-plugins) or plain old [hooks](./hooks) to create a connection.
+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.
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 895856f0..13f63588 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](./root-hook-plugins) are the preferred mechanism for setting root hooks.
+As of v8.0.0, [Root Hook Plugins](/next/features/root-hook-plugins) are the preferred mechanism for setting root hooks.
## Delayed Root Suite
:::caution
-Delayed root suites are incompatible with [parallel mode](./parallel-mode).
+Delayed root suites are incompatible with [parallel mode](/next/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 24a514aa..c0015ff7 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`](../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`](/next/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`](../reporters/json-stream)
-- [`markdown`](../reporters/markdown)
-- [`progress`](../reporters/progress)
+- [`json-stream`](/next/reporters/json-stream)
+- [`markdown`](/next/reporters/markdown)
+- [`progress`](/next/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`](../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. 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. 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`](../running/cli#--file-file)
-- [`--sort`](../running/cli#--sort--s)
-- [`--delay`](../running/cli#--delay)
+- [`--file`](/next/running/cli#--file-file)
+- [`--sort`](/next/running/cli#--sort--s)
+- [`--delay`](/next/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](../running/cli#--timeout-ms--t-ms) or [otherwise](./timeouts).
+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).
## "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](./root-hook-plugins) system.
+1. _Recommended_: Define root hooks in a "required" file, using the [Root Hook Plugin](/next/features/root-hook-plugins) system.
-If you need to run some code _once and only once_, use a [global fixture](./global-fixtures) instead.
+If you need to run some code _once and only once_, use a [global fixture](/next/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`](../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`](/next/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](../running/configuring); options set in config files will be merged with any command-line option.
+- ✅ Double-check your [config file](/next/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](./root-hook-plugins).
+ Move them into a [Root Hook Plugin](/next/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`](../running/cli#--timeout-ms--t-ms))
+- ✅ If tests are unexpectedly timing out, you may need to increase the default test timeout (via [`--timeout`](/next/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](../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](/next/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 564b55da..4a22997d 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](./hooks) before (or after) every test in every file.
+In some cases, you may want a [hook](/next/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](./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](/next/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`](../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`](/next/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()`](../running/browsers)
+In browsers you can set root hooks directly via a `rootHooks` object: `mocha.setup({ rootHooks: { beforeEach() {...} } })`, see [`mocha.setup()`](/next/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](./global-fixtures).
+If you need to ensure code runs once and only once in any mode, use [global fixtures](/next/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](../running/configuring) with `{"require": "test/hooks.js"}`) when running your tests.
+1. Use `--require test/hooks.js` (even better: use a [config file](/next/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`](../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`](/next/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 e2d27610..84fedf6e 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](./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
+- [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
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 a7e10539..4f08f403 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](./configuring).
+Browser Mocha supports many, but not all [CLI options](/next/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](./configuring)
+### Options That Differ Slightly From [CLI Options](/next/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](../reporters/spec) as well.
+It is possible to use [built-in reporters](/next/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 4f25ca95..79ebba50 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](../features/hooks#delayed-root-suite).
+See [Delayed Root Suite](/next/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`](../declaring/exclusive-tests) until you find the test that causes Mocha to hang
+- Use [`.only`](/next/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](../features/parallel-mode).
+Read more about [running tests in parallel](/next/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](./configuring).
+Specify an explicit path to a [configuration file](/next/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](./configuring) instead.
+Please use [configuration file](/next/running/configuring) instead.
:::
### `--package <path>`
@@ -388,7 +388,7 @@ Please use [configuration file](./configuring) instead.
:::note[New in v6.0.0]
:::
-Specify an explicit path to a [`package.json` file](./configuring) (ostensibly containing configuration in a `mocha` property).
+Specify an explicit path to a [`package.json` file](/next/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](../features/parallel-mode).
+`--file` is incompatible with [parallel mode](/next/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](../features/root-hook-plugins).
+If you want to set hooks to run, e.g., before each test, use a [Root Hook Plugin](/next/features/root-hook-plugins).
:::
:::note
-As of v8.0.0, Mocha supports `--require` for [NodeJS native ESM](../explainers/nodejs-native-esm-support).
+As of v8.0.0, Mocha supports `--require` for [NodeJS native ESM](/next/explainers/nodejs-native-esm-support).
There is no separate `--import` flag.
:::
### `--sort, -S`
:::caution
-`--sort` is incompatible with [parallel mode](../features/parallel-mode).
+`--sort` is incompatible with [parallel mode](/next/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](./configuring).
+`node` flags can be defined in Mocha's [configuration](/next/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](./configuring).
+[V8](https://v8.dev/) flags can be defined in Mocha's [configuration](/next/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 45f8c2ea..bfe3403d 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"`](../explainers/nodejs-native-esm-support) in your `package.json`)
+- **JavaScript**: Create a `.mocharc.js` (or `.mocharc.cjs` when using [`"type"="module"`](/next/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.
diff --git a/docs/README.md b/docs/README.md
index a6b6436e..9c123c98 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,18 +1,19 @@
# mochajs.org
-_So you wanna build the site?_
+These are the docs for the classic version of mochajs.org. For the Astro site released in 2025, see docs-next.
-[mochajs.org](https://mochajs.org) is built using [Eleventy](https://www.11ty.io/), a simple static site generator.
+The classic [mochajs.org](https://mochajs.org) is built using [Eleventy](https://www.11ty.io/), a simple static site generator.
## Development
1. Run `npm install` / `npm ci` from working copy root to get Node.js deps.
1. To include the API documentation, run `npm run docs:api` before the either of the following commands.
-1. To serve the site and rebuild as changes are made, execute `npm run docs-watch`.
-1. To rebuild the site _once_, execute `npm run docs`.
+1. To serve the site and rebuild as changes are made, run `npm run docs-watch`.
+1. To rebuild the site _once_, run `npm run docs`. This also builds the Astro site.
+1. To preview the site, run `npm run docs:preview`. The Astro site is available at `/next`.
### Notes
- The content lives in `docs/index.md`; everything else is markup, scripts, assets, etc.
- This file (`docs/README.md`) should _not_ be included in the build.
-- `docs/_site_` is where the deployed site lives. This directories are _not_ under version control.
+- `docs/_site_` is where the deployed site lives. This directory is _not_ under version control.