Skip to content

Commit

Permalink
Add link checking to docs build step (#3972)
Browse files Browse the repository at this point in the history 
* Add link checking to docs build step

* Update hyperlink to 4.3.0

* Update @mocha/docdash to 2.1.2

* Fix internal broken fragment links from jsdoc comments to front page

* Mark source code line fragment link checks as TODO. They are runtime JS generated and can't be found by hyperlink

* Document reporters.Base.prototype.epilogue as a member of the right thing, thus not breaking docs links

* Update to hyperlink 4.3.1

* Update to jsdoc 3.6.3

* experiment: add acorn 7 as dev dependency to attempt to fix broken build

* Fix broken links from tutorial. Use jsdoc link functionality instead of guessign url's

* Make hyperlink skipfilter argument windows compatible
  • Loading branch information
@Munter @boneskull
Munter authored and boneskull committed Oct 18, 2019
1 parent ef6c820 commit aca8895
Show file tree
Hide file tree
Showing 7 changed files with 477 additions and 103 deletions.
49 changes: 21 additions & 28 deletions docs/api-tutorials/custom-reporter.md
View file
Expand Up @@ -77,44 +77,37 @@ For further examples, the built-in reporter implementations are the [best place

## The `Base` Reporter Class

[Base] is an "abstract" class. It contains console-specific settings and utilities, commonly used by built-in reporters. Browsing the built-in reporter implementations, you may often see static properties of [Base] referenced.
[Base]{@link Mocha.reporters.Base} is an "abstract" class. It contains console-specific settings and utilities, commonly used by built-in reporters. Browsing the built-in reporter implementations, you may often see static properties of [Base]{@link Mocha.reporters.Base} referenced.

It's often useful--but not necessary--for a custom reporter to extend [Base].
It's often useful--but not necessary--for a custom reporter to extend [Base]{@link Mocha.reporters.Base}.

## Statistics

Mocha adds a `stats` property of type [StatsCollector](/api/module-lib_stats-collector.html) to the reporter's `Runner` instance (passed as first argument to constructor).
Mocha adds a `stats` property of type {@link StatsCollector} to the reporter's `Runner` instance (passed as first argument to constructor).

## Events

A reporter should listen for events emitted from the `runner` (a singleton instance of [Runner]).
A reporter should listen for events emitted from the `runner` (a singleton instance of {@link Runner}).

The event names are exported from the `constants` property of `Mocha.Runner`:

| Constant | Event Name | Event Arguments | Description |
| -------------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------- |
| `EVENT_RUN_BEGIN` | `start` | _(n/a)_ | Execution will begin. |
| `EVENT_RUN_END` | `end` | _(n/a)_ | All [Suite]s, [Test]s and [Hook]s have completed execution. |
| `EVENT_DELAY_BEGIN` | `waiting` | _(n/a)_ | Waiting for `global.run()` to be called; only emitted when [delay] option is `true`. |
| `EVENT_DELAY_END` | `ready` | _(n/a)_ | User called `global.run()` and the root suite is ready to execute. |
| `EVENT_SUITE_BEGIN` | `suite` | `Suite` | The [Hook]s and [Test]s within a [Suite] will be executed, including any nested [Suite]s. |
| `EVENT_SUITE_END` | `suite end` | `Suite` | The [Hook]s, [Test]s, and nested [Suite]s within a [Suite] have completed execution. |
| `EVENT_HOOK_BEGIN` | `hook` | `Hook` | A [Hook] will be executed. |
| `EVENT_HOOK_END` | `hook end` | `Hook` | A [Hook] has completed execution. |
| `EVENT_TEST_BEGIN` | `test` | `Test` | A [Test] will be executed. |
| `EVENT_TEST_END` | `test end` | `Test` | A [Test] has completed execution. |
| `EVENT_TEST_FAIL` | `fail` | `Test`, `Error` | A [Test] has failed or thrown an exception. |
| `EVENT_TEST_PASS` | `pass` | `Test` | A [Test] has passed. |
| `EVENT_TEST_PENDING` | `pending` | `Test` | A [Test] was skipped. |
| `EVENT_TEST_RETRY` | `retry` | `Test`, `Error` | A [Test] failed, but is about to be retried; only emitted if the `retry` option is nonzero. |
| Constant | Event Name | Event Arguments | Description |
| -------------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `EVENT_RUN_BEGIN` | `start` | _(n/a)_ | Execution will begin. |
| `EVENT_RUN_END` | `end` | _(n/a)_ | All [Suites]{@link Suite}, [Tests]{@link Test} and [Hooks]{@link Hook} have completed execution. |
| `EVENT_DELAY_BEGIN` | `waiting` | _(n/a)_ | Waiting for `global.run()` to be called; only emitted when [delay](/#delayed-root-suite) option is `true`. |
| `EVENT_DELAY_END` | `ready` | _(n/a)_ | User called `global.run()` and the root suite is ready to execute. |
| `EVENT_SUITE_BEGIN` | `suite` | `Suite` | The [Hooks]{@link Hook} and [Tests]{@link Test} within a {@link Suite} will be executed, including any nested [Suites]{@link Suite}. |
| `EVENT_SUITE_END` | `suite end` | `Suite` | The [Hooks]{@link Hook}, [Tests]{@link Test}, and nested [Suites]{@link Suite} within a {@link Suite} have completed execution. |
| `EVENT_HOOK_BEGIN` | `hook` | `Hook` | A {@link Hook} will be executed. |
| `EVENT_HOOK_END` | `hook end` | `Hook` | A {@link Hook} has completed execution. |
| `EVENT_TEST_BEGIN` | `test` | `Test` | A {@link Test} will be executed. |
| `EVENT_TEST_END` | `test end` | `Test` | A {@link Test} has completed execution. |
| `EVENT_TEST_FAIL` | `fail` | `Test`, `Error` | A {@link Test} has failed or thrown an exception. |
| `EVENT_TEST_PASS` | `pass` | `Test` | A {@link Test} has passed. |
| `EVENT_TEST_PENDING` | `pending` | `Test` | A {@link Test} was skipped. |
| `EVENT_TEST_RETRY` | `retry` | `Test`, `Error` | A {@link Test} failed, but is about to be retried; only emitted if the `retry` option is nonzero. |

**Please use these constants** instead of the event names in your own reporter! This will ensure compatibility with future versions of Mocha.

> It's important to understand that all `Suite` callbacks will be run _before_ the [Runner] emits `EVENT_RUN_BEGIN`. Hooks and tests, however, won't run until _after_ the [Runner] emits `EVENT_RUN_BEGIN`.
[runner]: /api/runner.html
[test]: /api/test.html
[hook]: /api/hook.html
[suite]: /api/suite.html
[base]: /api/mocha.reporters.base.html
[delay]: /#delayed-root-suite.html
> It's important to understand that all `Suite` callbacks will be run _before_ the {@link Runner} emits `EVENT_RUN_BEGIN`. Hooks and tests, however, won't run until _after_ the {@link Runner} emits `EVENT_RUN_BEGIN`.
1 change: 1 addition & 0 deletions lib/cli/options.js
View file
Expand Up @@ -203,6 +203,7 @@ module.exports = function getOptions() {
* @param {string|boolean} [args.opts] - Filepath to mocha.opts; defaults to whatever's in `mocharc.opts`, or `false` to skip
* @returns {external:yargsParser.Arguments|void} If read, object containing parsed arguments
* @memberof module:lib/cli/options
* @see {@link /#mochaopts|mocha.opts}
* @public
*/
const loadMochaOpts = (args = {}) => {
Expand Down
32 changes: 15 additions & 17 deletions lib/mocha.js
View file
Expand Up @@ -163,7 +163,7 @@ function Mocha(options) {
* Enables or disables bailing on the first failure.
*
* @public
* @see {@link https://mochajs.org/#-b---bail|CLI option}
* @see {@link /#-bail-b|CLI option}
* @param {boolean} [bail=true] - Whether to bail on first error.
* @returns {Mocha} this
* @chainable
Expand All @@ -184,7 +184,7 @@ Mocha.prototype.bail = function(bail) {
* Useful for generic setup code that must be included within test suite.
*
* @public
* @see {@link https://mochajs.org/#--file-file|CLI option}
* @see {@link /#-file-filedirectoryglob|CLI option}
* @param {string} file - Pathname of file to be loaded.
* @returns {Mocha} this
* @chainable
Expand All @@ -198,8 +198,8 @@ Mocha.prototype.addFile = function(file) {
* Sets reporter to `reporter`, defaults to "spec".
*
* @public
* @see {@link https://mochajs.org/#-r---reporter-name|CLI option}
* @see {@link https://mochajs.org/#reporters|Reporters}
* @see {@link /#-reporter-name-r-name|CLI option}
* @see {@link /#reporters|Reporters}
* @param {String|Function} reporter - Reporter name or constructor.
* @param {Object} [reporterOptions] - Options used to configure the reporter.
* @returns {Mocha} this
Expand Down Expand Up @@ -265,8 +265,8 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
* Sets test UI `name`, defaults to "bdd".
*
* @public
* @see {@link https://mochajs.org/#-u---ui-name|CLI option}
* @see {@link https://mochajs.org/#interfaces|Interface DSLs}
* @see {@link /#-ui-name-u-name|CLI option}
* @see {@link /#interfaces|Interface DSLs}
* @param {string|Function} [ui=bdd] - Interface name or class.
* @returns {Mocha} this
* @chainable
Expand Down Expand Up @@ -404,7 +404,7 @@ Mocha.prototype.fgrep = function(str) {
* <strong>Previous filter value will be overwritten on each call!</strong>
*
* @public
* @see {@link https://mochajs.org/#-g---grep-pattern|CLI option}
* @see {@link /#grep-regexp-g-regexp|CLI option}
* @see {@link Mocha#fgrep}
* @see {@link Mocha#invert}
* @param {RegExp|String} re - Regular expression used to select tests.
Expand Down Expand Up @@ -474,7 +474,7 @@ Mocha.prototype.ignoreLeaks = function(ignoreLeaks) {
* Enables checking for global variables leaked while running tests.
*
* @public
* @see {@link https://mochajs.org/#--check-leaks|CLI option}
* @see {@link /#-check-leaks|CLI option}
* @see {@link Mocha#ignoreLeaks}
* @return {Mocha} this
* @chainable
Expand Down Expand Up @@ -544,7 +544,7 @@ Mocha.prototype._growl = growl.notify;
* Specifies whitelist of variable names to be expected in global scope.
*
* @public
* @see {@link https://mochajs.org/#-global-variable-name|CLI option}
* @see {@link /#-global-variable-name|CLI option}
* @see {@link Mocha#checkLeaks}
* @param {String[]|String} globals - Accepted global variable name(s).
* @return {Mocha} this
Expand Down Expand Up @@ -615,9 +615,8 @@ Mocha.prototype.hideDiff = function(hideDiff) {
* If the value is `0`, timeouts will be disabled.
*
* @public
* @see {@link https://mochajs.org/#-t---timeout-ms|CLI option}
* @see {@link https://mochajs.org/#--no-timeouts|CLI option}
* @see {@link https://mochajs.org/#timeouts|Timeouts}
* @see {@link /#-timeout-ms-t-ms|CLI option}
* @see {@link /#timeouts|Timeouts}
* @see {@link Mocha#enableTimeouts}
* @param {number|string} msecs - Timeout threshold value.
* @return {Mocha} this
Expand All @@ -640,7 +639,7 @@ Mocha.prototype.timeout = function(msecs) {
* Sets the number of times to retry failed tests.
*
* @public
* @see {@link https://mochajs.org/#retry-tests|Retry Tests}
* @see {@link /#retry-tests|Retry Tests}
* @param {number} retry - Number of times to retry failed tests.
* @return {Mocha} this
* @chainable
Expand All @@ -658,7 +657,7 @@ Mocha.prototype.retries = function(n) {
* Sets slowness threshold value.
*
* @public
* @see {@link https://mochajs.org/#-s---slow-ms|CLI option}
* @see {@link /#-slow-ms-s-ms|CLI option}
* @param {number} msecs - Slowness threshold value.
* @return {Mocha} this
* @chainable
Expand All @@ -680,8 +679,7 @@ Mocha.prototype.slow = function(msecs) {
* Enables or disables timeouts.
*
* @public
* @see {@link https://mochajs.org/#-t---timeout-ms|CLI option}
* @see {@link https://mochajs.org/#--no-timeouts|CLI option}
* @see {@link /#-timeout-ms-t-ms|CLI option}
* @param {boolean} enableTimeouts - Whether to enable timeouts.
* @return {Mocha} this
* @chainable
Expand Down Expand Up @@ -737,7 +735,7 @@ Mocha.prototype.allowUncaught = function() {
* Used to perform asynch operations before any suites are run.
*
* @public
* @see {@link https://mochajs.org/#delayed-root-suite|delayed root suite}
* @see {@link /#delayed-root-suite|delayed root suite}
* @returns {Mocha} this
* @chainable
*/
Expand Down
2 changes: 1 addition & 1 deletion lib/reporters/base.js
View file
Expand Up @@ -307,7 +307,7 @@ function Base(runner, options) {
* Outputs common epilogue used by many of the bundled reporters.
*
* @public
* @memberof Mocha.reporters.Base
* @memberof Mocha.reporters
*/
Base.prototype.epilogue = function() {
var stats = this.stats;
Expand Down

0 comments on commit aca8895

Please sign in to comment.