Skip to content

armgit / mocha

Public Imported from GitHub
0

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

update docs regarding ESM and root hook plugins

Christopher Hiller0a66259da0de
diff --git a/docs/index.md b/docs/index.md
index 3a053505..1fa8ada2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1277,9 +1277,11 @@ A _Root Hook Plugin_ is a JavaScript file loaded via [`--require`](#-require-mod
### Defining a Root Hook Plugin
-A Root Hook Plugin file is a script which exports (via `module.exports`) a `mochaHooks` property.
+A Root Hook Plugin file is a script which exports (via `module.exports`) a `mochaHooks` property. It is loaded via `--require <file>`.
-Here's a simple example, which defines a root hook. Use it via `--require test/hooks.js`:
+Here's a simple example which defines a root hook, written using CJS and ESM syntax.
+
+#### With CommonJS
```js
// test/hooks.js
@@ -1292,7 +1294,24 @@ exports.mochaHooks = {
};
```
-`beforeEach`--as you may have guessed--corresponds to a `beforeEach` in the default [`bdd`](#bdd) interface.
+#### With ES Modules
+
+We're using the `.mjs` extension in these examples.
+
+> _Tip: If you're having trouble getting ES modules to work, refer to [the Node.js documentation](https://nodejs.org/api/esm.html)._
+
+```js
+// test/hooks.mjs
+
+export const mochaHooks = {
+ beforeEach(done) {
+ // do something before every test
+ done();
+ }
+};
+```
+
+> _Note: Further examples will use ESM syntax._
### Available Root Hooks
@@ -1313,10 +1332,12 @@ Available root hooks and their behavior:
{:.single-column}
-The root hook callbacks run in the usual context, so `this` is available:
+As with other hooks, `this` refers to to the current context object:
```js
-exports.mochaHooks = {
+// test/hooks.mjs
+
+export const mochaHooks = {
beforeAll() {
// skip all tests for bob
if (require('os').userInfo().username === 'bob') {
@@ -1331,7 +1352,9 @@ exports.mochaHooks = {
Multiple root hooks can be defined in a single plugin, for organizational purposes. For example:
```js
-exports.mochaHooks = {
+// test/hooks.mjs
+
+export const mochaHooks = {
beforeEach: [
function(done) {
// do something before every test,
@@ -1349,7 +1372,9 @@ exports.mochaHooks = {
If you need to perform some logic--such as choosing a root hook conditionally, based on the environment--`mochaHooks` can be a _function_ which returns the expected object.
```js
-exports.mochaHooks = () => {
+// test/hooks.mjs
+
+export const mochaHooks = () => {
if (process.env.CI) {
// root hooks object
return {
@@ -1375,7 +1400,9 @@ exports.mochaHooks = () => {
If you need to perform an async operation, `mochaHooks` can be `Promise`-returning:
```js
-exports.mochaHooks = async () => {
+// test/hooks.mjs
+
+export const mochaHooks = async () => {
const result = await checkSomething();
// only use a root hook if `result` is truthy
if (result) {
@@ -1423,7 +1450,7 @@ describe('my test suite', function() {
});
```
-Your `test/hooks.js` should contain:
+Your `test/hooks.js` (for this example, a CJS module) should contain:
```js
// test/hooks.js