+
+
diff --git a/docs-next/src/components/discord.svg b/docs-next/src/components/discord.svg
new file mode 100644
index 0000000000..6d343925da
--- /dev/null
+++ b/docs-next/src/components/discord.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs-next/src/components/icon-dark.svg b/docs-next/src/components/icon-dark.svg
new file mode 100644
index 0000000000..22942b2dc1
--- /dev/null
+++ b/docs-next/src/components/icon-dark.svg
@@ -0,0 +1,25 @@
+
diff --git a/docs-next/src/components/icon-light.svg b/docs-next/src/components/icon-light.svg
new file mode 100644
index 0000000000..eea6a062f6
--- /dev/null
+++ b/docs-next/src/components/icon-light.svg
@@ -0,0 +1,25 @@
+
diff --git a/docs-next/src/components/mocha-logo.svg b/docs-next/src/components/mocha-logo.svg
new file mode 100644
index 0000000000..fc4855b0a3
--- /dev/null
+++ b/docs-next/src/components/mocha-logo.svg
@@ -0,0 +1,63 @@
+
diff --git a/docs-next/src/components/mocha-thumbnail.svg b/docs-next/src/components/mocha-thumbnail.svg
new file mode 100644
index 0000000000..c585be45eb
--- /dev/null
+++ b/docs-next/src/components/mocha-thumbnail.svg
@@ -0,0 +1,68 @@
+
diff --git a/docs-next/src/components/openjsf-logo.svg b/docs-next/src/components/openjsf-logo.svg
new file mode 100644
index 0000000000..df9ab1f3b8
--- /dev/null
+++ b/docs-next/src/components/openjsf-logo.svg
@@ -0,0 +1,68 @@
+
+
+
diff --git a/docs-next/src/content/config.ts b/docs-next/src/content/config.ts
new file mode 100644
index 0000000000..a4eec59baa
--- /dev/null
+++ b/docs-next/src/content/config.ts
@@ -0,0 +1,6 @@
+import { defineCollection } from "astro:content";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+ docs: defineCollection({ schema: docsSchema() }),
+};
diff --git a/docs-next/src/content/data/sponsors.json b/docs-next/src/content/data/sponsors.json
new file mode 100644
index 0000000000..b7fc5aba93
--- /dev/null
+++ b/docs-next/src/content/data/sponsors.json
@@ -0,0 +1,12 @@
+[
+ {
+ "href": "https://localizejs.com",
+ "image": "https://images.opencollective.com/localize/bb2cd4d/logo/256.png",
+ "title": "Localize"
+ },
+ {
+ "href": "https://route4me.com",
+ "image": "https://images.opencollective.com/route4me/71fb6fa/avatar/256.png",
+ "title": "Route4Me Route Planner"
+ }
+]
diff --git a/docs-next/src/content/docs/api/example.mdx b/docs-next/src/content/docs/api/example.mdx
new file mode 100644
index 0000000000..0224f096ce
--- /dev/null
+++ b/docs-next/src/content/docs/api/example.mdx
@@ -0,0 +1,11 @@
+---
+title: Example Reference
+description: A reference page in my new Starlight docs site.
+---
+
+Reference pages are ideal for outlining how things work in terse and clear terms.
+Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
+
+## Further reading
+
+- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
diff --git a/docs-next/src/content/docs/declaring/dynamic-tests.mdx b/docs-next/src/content/docs/declaring/dynamic-tests.mdx
new file mode 100644
index 0000000000..f7deeb8b41
--- /dev/null
+++ b/docs-next/src/content/docs/declaring/dynamic-tests.mdx
@@ -0,0 +1,89 @@
+---
+description: Describing tests cases based on dynamic data.
+title: Dynamic Tests
+---
+
+Given Mocha's use of function expressions to define suites and test cases, it's straightforward to generate your tests dynamically.
+No special syntax is required — plain old JavaScript can be used to achieve functionality similar to "parameterized" tests, which you may have seen in other frameworks.
+
+Take the following example:
+
+```js
+const assert = require("assert");
+
+function add(args) {
+ return args.reduce((prev, curr) => prev + curr, 0);
+}
+
+describe("add()", function () {
+ const tests = [
+ { args: [1, 2], expected: 3 },
+ { args: [1, 2, 3], expected: 6 },
+ { args: [1, 2, 3, 4], expected: 10 },
+ ];
+
+ tests.forEach(({ args, expected }) => {
+ it(`correctly adds ${args.length} args`, function () {
+ const res = add(args);
+ assert.strictEqual(res, expected);
+ });
+ });
+});
+```
+
+The above code will produce a suite with three specs:
+
+```bash
+$ mocha
+
+ add()
+ ✓ correctly adds 2 args
+ ✓ correctly adds 3 args
+ ✓ correctly adds 4 args
+```
+
+Tests added inside a `.forEach` handler often don't play well with editor plugins, especially with "right-click run" features.
+Another way to parameterize tests is to generate them with a closure.
+This following example is equivalent to the one above:
+
+```js
+describe("add()", function () {
+ const testAdd = ({ args, expected }) =>
+ function () {
+ const res = add(args);
+ assert.strictEqual(res, expected);
+ };
+
+ it("correctly adds 2 args", testAdd({ args: [1, 2], expected: 3 }));
+ it("correctly adds 3 args", testAdd({ args: [1, 2, 3], expected: 6 }));
+ it("correctly adds 4 args", testAdd({ args: [1, 2, 3, 4], expected: 10 }));
+});
+```
+
+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`.
+
+```js
+// testfile.mjs
+import assert from "assert";
+
+// top-level await: Node >= v14.8.0 with ESM test file
+const tests = await new Promise((resolve) => {
+ setTimeout(resolve, 5000, [
+ { args: [1, 2], expected: 3 },
+ { args: [1, 2, 3], expected: 6 },
+ { args: [1, 2, 3, 4], expected: 10 },
+ ]);
+});
+
+// in suites ASYNCHRONOUS callbacks are NOT supported
+describe("add()", function () {
+ tests.forEach(({ args, expected }) => {
+ it(`correctly adds ${args.length} args`, function () {
+ const res = args.reduce((sum, curr) => sum + curr, 0);
+ assert.strictEqual(res, expected);
+ });
+ });
+});
+```
diff --git a/docs-next/src/content/docs/declaring/exclusive-tests.mdx b/docs-next/src/content/docs/declaring/exclusive-tests.mdx
new file mode 100644
index 0000000000..6a480bb6b6
--- /dev/null
+++ b/docs-next/src/content/docs/declaring/exclusive-tests.mdx
@@ -0,0 +1,112 @@
+---
+description: Describing test cases that should be run to the exclusion of other tests.
+title: Exclusive Tests
+---
+
+:::caution
+Exclusive tests are incompatible with [parallel mode](../features/parallel-mode).
+:::
+
+The exclusivity feature allows you to run _only_ the specified suite or test-case
+by appending `.only()` to the function.
+Here's an example of executing only a particular suite:
+
+```js
+describe("Array", function () {
+ describe.only("#indexOf()", function () {
+ // ...
+ });
+});
+```
+
+_Note_: All nested suites will still be executed.
+
+Here's an example of executing an individual test case:
+
+```js
+describe("Array", function () {
+ describe("#indexOf()", function () {
+ it.only("should return -1 unless present", function () {
+ // ...
+ });
+
+ it("should return the index when present", function () {
+ // ...
+ });
+ });
+});
+```
+
+Previous to v3.0.0, `.only()` used string matching to decide which tests to execute; this is no longer the case.
+In v3.0.0 or newer, `.only()` can be used multiple times to define a subset of tests to run:
+
+```js
+describe("Array", function () {
+ describe("#indexOf()", function () {
+ it.only("should return -1 unless present", function () {
+ // this test will be run
+ });
+
+ it.only("should return the index when present", function () {
+ // this test will also be run
+ });
+
+ it("should return -1 if called with a non-Array context", function () {
+ // this test will not be run
+ });
+ });
+});
+```
+
+You may also choose multiple suites:
+
+```js
+describe("Array", function () {
+ describe.only("#indexOf()", function () {
+ it("should return -1 unless present", function () {
+ // this test will be run
+ });
+
+ it("should return the index when present", function () {
+ // this test will also be run
+ });
+ });
+
+ describe.only("#concat()", function () {
+ it("should return a new Array", function () {
+ // this test will also be run
+ });
+ });
+
+ describe("#slice()", function () {
+ it("should return a new Array", function () {
+ // this test will not be run
+ });
+ });
+});
+```
+
+But _tests will have precedence_:
+
+```js
+describe("Array", function () {
+ describe.only("#indexOf()", function () {
+ it.only("should return -1 unless present", function () {
+ // this test will be run
+ });
+
+ it("should return the index when present", function () {
+ // this test will not be run
+ });
+ });
+});
+```
+
+:::note
+Hooks, if present, will still be executed.
+:::
+
+:::tip
+Be mindful not to commit usages of `.only()` to version control, unless you really mean it!
+To do so one can run mocha with the option `--forbid-only` in the continuous integration test command (or in a git precommit hook).
+:::
diff --git a/docs-next/src/content/docs/declaring/inclusive-tests.mdx b/docs-next/src/content/docs/declaring/inclusive-tests.mdx
new file mode 100644
index 0000000000..c4a4c989cf
--- /dev/null
+++ b/docs-next/src/content/docs/declaring/inclusive-tests.mdx
@@ -0,0 +1,127 @@
+---
+description: Describing test cases that should not be run yet.
+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.
+Here's an example of skipping an individual test:
+
+```js
+describe("Array", function () {
+ describe("#indexOf()", function () {
+ it.skip("should return -1 unless present", function () {
+ // this test will not be run
+ });
+
+ it("should return the index when present", function () {
+ // this test will be run
+ });
+ });
+});
+```
+
+You can also put `.skip()` on an entire suite.
+This is equivalent to appending `.skip()` onto all tests in the suite.
+Hooks in the suite are also skipped.
+
+```js
+describe("Array", function () {
+ describe.skip("#indexOf()", function () {
+ it("should return -1 unless present", function () {
+ // this test will not be run
+ });
+ });
+});
+```
+
+_Note_: Code in skipped suites, that is placed outside of hooks or tests is still executed, as mocha will still invoke the suite function to build up the suite structure for visualization.
+
+:::tip[Best practice]
+Use `.skip()` instead of commenting tests out.
+:::
+
+You may also skip _at runtime_ using `this.skip()`.
+If a test needs an environment or configuration which cannot be detected beforehand, a runtime skip is appropriate.
+For example:
+
+```js
+it('should only test in the correct environment', function() {
+ if (/* check test environment */) {
+ // make assertions
+ } else {
+ this.skip();
+ }
+});
+```
+
+The above test will be reported as [pending](./pending-tests).
+It's also important to note that calling `this.skip()` will effectively _abort_ the test.
+
+:::tip[Best practice]
+To avoid confusion, do not execute further instructions in a test or hook after calling `this.skip()`.
+:::
+
+Contrast the above test with the following code:
+
+```js
+it('should only test in the correct environment', function() {
+ if (/* check test environment */) {
+ // make assertions
+ } else {
+ // do nothing
+ }
+});
+```
+
+Because this test _does nothing_, it will be reported as _passing_.
+
+:::tip[Best practice]
+Don't do nothing!
+A test should make an assertion or use `this.skip()`.
+:::
+
+To skip _multiple_ tests in this manner, use `this.skip()` in a "before all" hook:
+
+```js
+before(function() {
+ if (/* check test environment */) {
+ // setup code
+ } else {
+ this.skip();
+ }
+});
+```
+
+This will skip all `it`, `beforeEach/afterEach`, and `describe` blocks within the suite.
+`before/after` hooks are skipped unless they are defined at the same level as the hook containing `this.skip()`.
+
+```js
+describe("outer", function () {
+ before(function () {
+ this.skip();
+ });
+
+ after(function () {
+ // will be executed
+ });
+
+ describe("inner", function () {
+ before(function () {
+ // will be skipped
+ });
+
+ after(function () {
+ // will be skipped
+ });
+ });
+});
+```
+
+:::note[Updated in v7.0.0]
+Skipping a test within an "after all" hook is disallowed and will throw an exception.
+Use a return statement or other means to abort hook execution.
+:::
+
+Before Mocha v3.0.0, `this.skip()` was not supported in asynchronous tests and hooks.
diff --git a/docs-next/src/content/docs/declaring/pending-tests.mdx b/docs-next/src/content/docs/declaring/pending-tests.mdx
new file mode 100644
index 0000000000..295e755333
--- /dev/null
+++ b/docs-next/src/content/docs/declaring/pending-tests.mdx
@@ -0,0 +1,20 @@
+---
+description: Describing test cases with names that don't yet have a callback.
+title: Pending Tests
+---
+
+"Pending" — as in "someone should write these test cases eventually" — test-cases are those _without_ a callback:
+
+```js
+describe("Array", function () {
+ describe("#indexOf()", function () {
+ // pending test below
+ it("should return -1 when the value is not present");
+ });
+});
+```
+
+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()`.
diff --git a/docs-next/src/content/docs/declaring/retrying-tests.mdx b/docs-next/src/content/docs/declaring/retrying-tests.mdx
new file mode 100644
index 0000000000..7a71398cbd
--- /dev/null
+++ b/docs-next/src/content/docs/declaring/retrying-tests.mdx
@@ -0,0 +1,32 @@
+---
+description: Describing test cases that should retry on failure.
+title: Retry Tests
+---
+
+You can choose to retry failed tests up to a certain number of times.
+This feature is designed to handle end-to-end tests (functional tests/Selenium...) where resources cannot be easily mocked/stubbed.
+**It's not recommended to use this feature for unit tests**.
+
+This feature does re-run a failed test and its corresponding `beforeEach/afterEach` hooks, but not `before/after` hooks.
+`this.retries()` has no effect on failing hooks.
+
+:::note
+Example below was written using Selenium webdriver (which [overwrites global Mocha hooks](https://github.com/SeleniumHQ/selenium/blob/c10e8a955883f004452cdde18096d70738397788/javascript/node/selenium-webdriver/testing/index.js) for `Promise` chain).
+:::
+
+```js
+describe("retries", function () {
+ // Retry all tests in this suite up to 4 times
+ this.retries(4);
+
+ beforeEach(function () {
+ browser.get("http://www.yahoo.com");
+ });
+
+ it("should succeed by the 3rd try", function () {
+ // Specify this test to only retry up to 2 times
+ this.retries(2);
+ expect($(".foo").isDisplayed()).to.eventually.be.true;
+ });
+});
+```
diff --git a/docs-next/src/content/docs/explainers/detecting-multiple-calls-to-done.mdx b/docs-next/src/content/docs/explainers/detecting-multiple-calls-to-done.mdx
new file mode 100644
index 0000000000..55571d9d56
--- /dev/null
+++ b/docs-next/src/content/docs/explainers/detecting-multiple-calls-to-done.mdx
@@ -0,0 +1,36 @@
+---
+description: Why Mocha determines if the done() callback in a test was called multiple times.
+title: Detecting Multiple Calls to done()
+---
+
+If you use callback-based async tests, Mocha will throw an error if `done()` is called multiple times.
+This is handy for catching accidental double callbacks.
+
+```javascript
+it("double done", function (done) {
+ // Calling `done()` twice is an error
+ setImmediate(done);
+ setImmediate(done);
+});
+```
+
+Running the above test will give you the below error message:
+
+```bash
+$ ./node_modules/.bin/mocha mocha.test.js
+
+
+ ✓ double done
+ 1) double done
+
+ 1 passing (6ms)
+ 1 failing
+
+ 1) double done:
+ Error: done() called multiple times
+ at Object. (mocha.test.js:1:63)
+ at require (internal/module.js:11:18)
+ at Array.forEach ()
+ at startup (bootstrap_node.js:187:16)
+ at bootstrap_node.js:608:3
+```
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
new file mode 100644
index 0000000000..0350d2125a
--- /dev/null
+++ b/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdx
@@ -0,0 +1,33 @@
+---
+description: A mid-level outline of Mocha's "flow of execution".
+title: Node.js Native ESM Support
+---
+
+:::note[New in v7.1.0]
+:::
+
+Mocha supports writing your tests as ES modules, and not just using CommonJS.
+For example:
+
+```js
+// test.mjs
+import { add } from "./add.mjs";
+import assert from "assert";
+
+it("should add to numbers from an es module", () => {
+ assert.equal(add(3, 5), 8);
+});
+```
+
+To enable this you don't need to do anything special.
+Write your test file as an ES module.
+In Node.js this means either ending the file with a `.mjs` extension, or, if you want to use the regular `.js` extension, by adding `"type": "module"` to your `package.json`.
+More information can be found in the [Node.js documentation](https://nodejs.org/api/esm.html).
+
+### 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`)
+- When using module-level mocks via libs like `proxyquire`, `rewiremock` or `rewire`, hold off on using ES modules for your test files.
+ You can switch to using `testdouble`, which does support ESM.
diff --git a/docs-next/src/content/docs/explainers/reporter-spec-duration.png b/docs-next/src/content/docs/explainers/reporter-spec-duration.png
new file mode 100644
index 0000000000..d48e750e3e
Binary files /dev/null and b/docs-next/src/content/docs/explainers/reporter-spec-duration.png differ
diff --git a/docs-next/src/content/docs/explainers/run-cycle-overview.mdx b/docs-next/src/content/docs/explainers/run-cycle-overview.mdx
new file mode 100644
index 0000000000..959c86f99f
--- /dev/null
+++ b/docs-next/src/content/docs/explainers/run-cycle-overview.mdx
@@ -0,0 +1,55 @@
+---
+description: A mid-level outline of Mocha's "flow of execution".
+title: Run Cycle Overview
+---
+
+The following is a mid-level outline of Mocha’s "flow of execution" when run in Node.js; the "less important" details have been omitted.
+
+In a browser, test files are loaded by `
+
+
+
+
+
+
+
+