Skip to content

armgit / mocha

Public Imported from GitHub
0

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

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

Mark Wiemerfbceb19bbdad
diff --git a/docs-next/src/content/docs/declaring/dynamic-tests.mdx b/docs-next/src/content/docs/declaring/dynamic-tests.mdx
index f7deeb8b..08b7425b 100644
--- 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 — 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
index c4a4c989..056583be 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](./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
index 295e7553..fbd0ac4a 100644
--- 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
index 7a71398c..a89b65fd 100644
--- 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
index 4b90ba6f..82c9ee20 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 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
index 516ae49a..ec694ffe 100644
--- 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 — 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
index fdff81ab..83a95b41 100644
--- 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
index 062827d4..895856f0 100644
--- 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
index 8a6a53fe..24a514aa 100644
--- 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
index c1d82bc4..564b55da 100644
--- 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
index e29680e7..4c28da72 100644
--- 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
index 3def0894..301e72a8 100644
--- 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
index 47b33063..ce53ac19 100644
--- 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
index 124dafe5..f9232ba4 100644
--- 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
index e3079d3b..4f25ca95 100644
--- 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 — because it's not always obvious where the problem is — 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 ⓡ ⓢ ⏎ (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
index 99d74159..448164da 100644
--- 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
index cb7800c1..8ba21f6d 100644
--- 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.