mochajs / mocha / 7309

93%

main: 94%

push

travis-ci

add Root Hook Plugins

(documentation will be in another PR)

Adds "root hook plugins", a system to define root hooks via files loaded with `--require`.

This enables root hooks to work in parallel mode.  Because parallel mode runs files in a non-deterministic order, and files do not share a `Mocha` instance, it is not possible to share these hooks with other test files.  This change also works well with third-party libraries for Mocha which need the behavior; these can now be trivially consumed by adding `--require` or `require: 'some-library'` in Mocha's config file.

The way it works is:

1. When a file is loaded via `--require`, we check to see if that file exports a property named `mochaHooks` (can be multiple files).
1. If it does, we save a reference to the property.
1. After Yargs' validation phase, we use async middleware to execute root hook plugin functions--or if they are objects, just collect them--and we flatten all hooks found into four buckets corresponding to the four hook types.
1. Once `Mocha` is instantiated, if it is given a `rootHooks` option, those hooks are applied to the root suite.

This works with parallel tests because we can save a reference to the flattened hooks in each worker process, and a new `Mocha` instance is created with them for each test file.

* * *

Tangential:

- Because a root hook plugin can be defined as an `async` function, I noticed that `utils.type()` does not return `function` for async functions; it returns `asyncfunction`.  I've added a (Node-specific, for now) test for this.

- `handleRequires` is now `async`, since it will need to be anyway to support ESM and calls to `import()`.

- fixed incorrect call to `fs.existsSync()`

Ref: #4198

1047 of 1221 branches covered (85.75%)

2786 of 2991 relevant lines covered (93.15%)

685.19 hits per line