docs: fix new website typos, improve readability (#5312)

mark-wiemer · web-flow · commit fbceb19bbdad · 2025-03-21T11:33:46.000-04:00
* Fix typos, improve readability

* Cleanup decision tree intro
diff --git a/docs-next/src/content/docs/declaring/dynamic-tests.mdx b/docs-next/src/content/docs/declaring/dynamic-tests.mdx
@@ -4,7 +4,7 @@ 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 &mdash; plain old JavaScript can be used to achieve functionality similar to "parameterized" tests, which you may have seen in other frameworks.
+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:
 
@@ -77,7 +77,7 @@ const tests = await new Promise((resolve) => {
   ]);
 });
 
-// in suites ASYNCHRONOUS callbacks are NOT supported
+// in suites, async callbacks are **not** supported
 describe("add()", function () {
   tests.forEach(({ args, expected }) => {
     it(`correctly adds ${args.length} args`, function () {
diff --git 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](./pending-tests) and reported as such.
 Here's an example of skipping an individual test:
 
 ```js
@@ -36,7 +36,7 @@ describe("Array", function () {
 });
 ```
 
-_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.
+_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.
diff --git a/docs-next/src/content/docs/declaring/pending-tests.mdx b/docs-next/src/content/docs/declaring/pending-tests.mdx
@@ -14,7 +14,7 @@ describe("Array", function () {
 });
 ```
 
-Pending tests will be included in the test results, and marked as pending.
+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
@@ -11,7 +11,7 @@ This feature does re-run a failed test and its corresponding `beforeEach/afterEa
 `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).
+The 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
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
@@ -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 which of [hooks](../features/hooks), [root hook plugins](../features/root-hook-plugins) or [global fixtures](../features/global-fixtures) you should use.
+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/assertions.mdx b/docs-next/src/content/docs/features/assertions.mdx
@@ -4,7 +4,7 @@ title: Assertions
 ---
 
 Mocha allows you to use any assertion library you wish.
-In many of this site's examples, we're using Node.js' built-in [assert](https://nodejs.org/api/assert.html) module &mdash; but generally, if it throws an `Error`, it will work!
+In many of this site's examples, we're using Node.js' built-in [assert](https://nodejs.org/api/assert.html) module--but generally, if it throws an `Error`, it will work!
 This means you can use libraries such as:
 
 - [better-assert](https://github.com/visionmedia/better-assert) - C-style self-documenting `assert()`
diff --git a/docs-next/src/content/docs/features/asynchronous-code.mdx b/docs-next/src/content/docs/features/asynchronous-code.mdx
@@ -3,8 +3,8 @@ description: Testing asynchronous code with Mocha
 title: Asynchronous Code
 ---
 
-By adding an argument (usually named `done`) to `it()` to a test callback, Mocha will know that it should wait for this function to be called to complete the test.
-This callback accepts both an `Error` instance (or subclass thereof) _or_ a falsy value; anything else is invalid usage and throws an error (usually causing a failed test).
+By adding an argument (usually named `done`) to a test callback, Mocha will know that it should wait for this function to be called to complete the test.
+This callback accepts both an `Error` instance _or_ a falsy value; anything else is invalid usage and throws an error (usually causing a failed test).
 
 ```js
 describe("User", function () {
diff --git a/docs-next/src/content/docs/features/hooks.mdx b/docs-next/src/content/docs/features/hooks.mdx
@@ -30,7 +30,7 @@ describe("hooks", function () {
 
 :::note
 Tests can appear before, after, or interspersed with your hooks.
-Hooks will run in the order they are defined, as appropriate; all `before()` hooks run (once), then any `beforeEach()` hooks, tests, any `afterEach()` hooks, and finally `after()` hooks (once).
+Hooks will run in the order they are defined, as appropriate: all `before()` hooks run (once), then any `beforeEach()` hooks, tests, any `afterEach()` hooks, and finally `after()` hooks (once).
 :::
 
 ## Describing Hooks
diff --git a/docs-next/src/content/docs/features/parallel-mode.mdx b/docs-next/src/content/docs/features/parallel-mode.mdx
@@ -112,8 +112,7 @@ 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 new (also as
-   of v8.0.0) [Root Hook Plugin](./root-hook-plugins) system.
+1. _Recommended_: Define root hooks in a "required" file, using the [Root Hook Plugin](./root-hook-plugins) system.
 
 If you need to run some code _once and only once_, use a [global fixture](./global-fixtures) instead.
 
@@ -133,7 +132,7 @@ If you find your tests don't work properly when run with [`--parallel`](../runni
 - ✅ 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.
-- ✅ Look for root hooks (they look like [this](#root-hooks-are-not-global)) in your tests.
+- ✅ Look for [root hooks](#root-hooks-are-not-global) in your tests.
   Move them into a [Root Hook Plugin](./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))
diff --git a/docs-next/src/content/docs/features/root-hook-plugins.mdx b/docs-next/src/content/docs/features/root-hook-plugins.mdx
@@ -14,7 +14,7 @@ For that reason, running root hooks using this method is _strongly discouraged_,
 
 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()`](../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
 
@@ -208,7 +208,7 @@ Your `test/hooks.js` (for this example, a CJS module) should contain:
 // test/hooks.js
 
 exports.mochaHooks = {
-  beforeEach: function () {
+  beforeAll: function () {
     // global setup for all tests
   },
   afterAll: function () {
diff --git a/docs-next/src/content/docs/features/timeouts.mdx b/docs-next/src/content/docs/features/timeouts.mdx
@@ -64,7 +64,7 @@ With async tests if you disable timeouts via `this.timeout(0)` and then do not c
 ## Diffs
 
 Mocha supports the `err.expected` and `err.actual` properties of any thrown `AssertionError`s from an assertion library.
-Mocha will attempt to display the difference between what was expected, and what the assertion actually saw.
+Mocha will attempt to display the difference between what was expected and what the assertion actually saw.
 Here's an example of a "string" diff using `--inline-diffs`:
 
 ![string diffs](./reporter-string-diffs.png)
diff --git a/docs-next/src/content/docs/reporters/markdown.mdx b/docs-next/src/content/docs/reporters/markdown.mdx
@@ -6,5 +6,5 @@ title: Markdown
 Alias: `Markdown`, `markdown`
 
 The Markdown reporter generates a markdown TOC and body for your test suite.
-This is great if you want to use the tests as documentation within a Github wiki page, or a markdown file in the repository that Github can render.
+This is great if you want to use the tests as documentation within a GitHub wiki page, or a markdown file in the repository that GitHub can render.
 For example, here is the Connect [test output](https://github.com/senchalabs/connect/blob/90a725343c2945aaee637e799b1cd11e065b2bff/tests.md).
diff --git a/docs-next/src/content/docs/reporters/xunit.mdx b/docs-next/src/content/docs/reporters/xunit.mdx
@@ -5,8 +5,7 @@ title: XUnit
 
 Alias: `XUnit`, `xunit`
 
-The XUnit reporter is also available.
-It outputs an XUnit-compatible XML document, often applicable in CI servers.
+The XUnit reporter outputs an XUnit-compatible XML document, often applicable in CI servers.
 
 By default, it will output to the console.
 To write directly to a file, use `--reporter-option output=filename.xml`.
diff --git a/docs-next/src/content/docs/running/browsers.mdx b/docs-next/src/content/docs/running/browsers.mdx
@@ -3,7 +3,7 @@ description: Running Mocha in Browsers
 title: Browsers
 ---
 
-Mocha runs in the browser.
+Mocha can run in the browser.
 Every release of Mocha will have new builds of `./mocha.js` and `./mocha.css` for use in the browser.
 
 A typical setup might look something like the following, where we call `mocha.setup('bdd')` to use the **BDD** interface before loading the test scripts, running them `onload` with `mocha.run()`.
diff --git a/docs-next/src/content/docs/running/cli.mdx b/docs-next/src/content/docs/running/cli.mdx
@@ -5,6 +5,8 @@ description: Running Mocha in your terminal.
 
 Running `npx mocha --help` will show the full list of available commands:
 
+{/* This output is defined in lib/cli/run.js */}
+
 ```plaintext
 mocha [spec..]
 
@@ -154,7 +156,7 @@ TL;DR: If your tests hang after an upgrade to Mocha v4.0.0 or newer, use `--exit
 :::
 
 _Prior to_ version v4.0.0, _by default_, Mocha would force its own process to exit once it was finished executing all tests.
-This behavior enables a set of potential problems; it's indicative of tests (or fixtures, harnesses, code under test, etc.) which don't clean up after themselves properly.
+This behavior enables a set of potential problems: it's indicative of tests (or fixtures, harnesses, code under test, etc.) which don't clean up after themselves properly.
 Ultimately, "dirty" tests can (but not always) lead to _false positive_ or _false negative_ results.
 
 "Hanging" most often manifests itself if a server is still listening on a port, or a socket is still open, etc.
@@ -163,7 +165,7 @@ It can also be something like a runaway `setInterval()`, or even an errant `Prom
 The _default behavior_ in v4.0.0 (and newer) is `--no-exit`, where previously it was `--exit`.
 
 **The easiest way to "fix" the issue is to pass `--exit` to the Mocha process.**
-It _can_ be time-consuming to debug &mdash; because it's not always obvious where the problem is &mdash; but it _is_ recommended to do so.
+It _can_ be time-consuming to debug--because it's not always obvious where the problem is--but it _is_ recommended to do so.
 
 To ensure your tests aren't leaving messes around, here are some ideas to get started:
 
@@ -184,7 +186,7 @@ If set to `true`, Mocha returns exit code `0` even if there are failed tests dur
 :::note[New in v9.1.0]
 :::
 
-Fail test run if no tests are encountered with `exit-code: 1`.
+Fail test run with `exit-code: 1` if no tests are encountered.
 
 ### `--forbid-only`
 
@@ -478,7 +480,7 @@ Rerun tests on file changes.
 
 The `--watch-files` and `--watch-ignore` options can be used to control which files are watched for changes.
 
-Tests may be rerun manually by typing &#x24e1; &#x24e2; &#x23ce; (same shortcut as `nodemon`).
+Tests may be rerun manually by typing `rs` and pressing enter (same shortcut as `nodemon`).
 
 ### `--watch-files <file|directory|glob>`
 
@@ -535,7 +537,7 @@ The same goes for any other part of a suite or test-case title, `--grep users` w
 And another option with double quotes: `--grep "groupA|groupB"`.
 
 And for more complex criteria: `--grep "/get/i"`.
-Some shells as e.g. Git-Bash-for-Windows may require: `--grep "'/get/i'"`.
+Some shells (e.g. Git Bash for Windows) may require: `--grep "'/get/i'"`.
 Using flags other than the `ignoreCase /i` (especially `/g` and `/y`) may lead to unpredictable results.
 
 ```js
@@ -602,7 +604,7 @@ You can also pass `node` flags to Node.js using [`--node-option`](#--node-option
 
 ### `--enable-source-maps`
 
-:::note[New in vNode.js v12.12.0]
+:::note[New in Node.js v12.12.0]
 :::
 
 If the [`--enable-source-maps`](https://nodejs.org/dist/latest-v12.x/docs/api/cli.html#cli_enable_source_maps) flag
@@ -618,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 flags can be defined in Mocha's [configuration](./configuring).
+[V8](https://v8.dev/) flags can be defined in Mocha's [configuration](./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
@@ -12,7 +12,7 @@ Mocha supports configuration files, typical of modern command-line tools, in sev
   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.
-  Comments &mdash; while not valid JSON &mdash; are allowed in this file, and will be ignored by Mocha.
+  Comments--while not valid JSON--are allowed in this file, and will be ignored by Mocha.
 - **package.json**: Create a `mocha` property in your project's `package.json`.
 
 ## Custom Locations
@@ -29,7 +29,7 @@ Likewise, use `--no-package` to stop Mocha from looking for configuration in a `
 
 ## Priorities
 
-If no custom path was given, and if there are multiple configuration files in the same directory, Mocha will search for &mdash; and use &mdash; only one.
+If no custom path was given, and if there are multiple configuration files in the same directory, Mocha will search for--and use--only one.
 The priority is:
 
 1. `.mocharc.js`
@@ -65,7 +65,7 @@ For example, a `.mocharc.json` containing `"require": "bar"`, coupled with execu
 ## Extending Configuration
 
 Configurations can inherit from other modules using the `extends` keyword.
-See [here](http://yargs.js.org/docs/#api-reference-configobject-extends-keyword) for more information.
+See [yargs API reference](http://yargs.js.org/docs/#api-reference-configobject-extends-keyword) for more information.
 
 ## Configuration Format
 
diff --git a/docs-next/src/content/docs/running/test-globs.mdx b/docs-next/src/content/docs/running/test-globs.mdx
@@ -24,6 +24,6 @@ You should _always_ quote your globs in npm scripts.
 If you use quotes, the [`glob`](https://www.npmjs.com/package/glob) module will handle its expansion.
 For maximum compatibility, surround the entire expression with double quotes and refrain from `$`, `"`, `^`, and `\` within your expression.
 
-See this [tutorial](https://gist.github.com/reggi/475793ea1846affbcfe8) on using globs.
+See this [tutorial on using globs](https://gist.github.com/reggi/475793ea1846affbcfe8).
 
 _Note_: Double quotes around the glob are recommended for portability.
