docs: improve third-party reporter docs (#5285)

* Improve hosted docs for `runnable` * Document usages of `Runner.constants` * Update lib/runnable.js Co-authored-by: Josh Goldberg ✨ <[email protected]> * Update lib/runnable.js --------- Co-authored-by: Josh Goldberg ✨ <[email protected]>
mochajs · Jan 6, 2025 · c5a0ef5 · c5a0ef5
1 parent 75dcf8c
commit c5a0ef5
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 2 deletions.
diff --git a/lib/runnable.js b/lib/runnable.js
@@ -24,8 +24,10 @@ var MAX_TIMEOUT = Math.pow(2, 31) - 1;
 
 module.exports = Runnable;
 
+// "Additional properties" doc comment added for hosted docs (mochajs.org/api)
 /**
  * Initialize a new `Runnable` with the given `title` and callback `fn`.
+ * Additional properties, like `getFullTitle()` and `slow()`, can be viewed in the `Runnable` source.
  *
  * @class
  * @extends external:EventEmitter

diff --git a/lib/runner.js b/lib/runner.js
@@ -47,7 +47,39 @@ var globals = [
 
 var constants = utils.defineConstants(
   /**
-   * {@link Runner}-related constants.
+   * {@link Runner}-related constants. Used by reporters. Each event emits the corresponding object, unless otherwise indicated.
+   * @example
+   * const Mocha = require('mocha');
+   * const Base = Mocha.reporters.Base;
+   * const {
+   *   EVENT_HOOK_BEGIN,
+   *   EVENT_TEST_PASS,
+   *   EVENT_TEST_FAIL,
+   *   EVENT_TEST_END
+   * } = Mocha.Runner.constants
+   *
+   * function MyReporter(runner, options) {
+   *   Base.call(this, runner, options);
+   *
+   *   runner.on(EVENT_HOOK_BEGIN, function(hook) {
+   *     console.log('hook called: ', hook.title);
+   *   });
+   *
+   *   runner.on(EVENT_TEST_PASS, function(test) {
+   *     console.log('pass: %s', test.fullTitle());
+   *   });
+   *
+   *   runner.on(EVENT_TEST_FAIL, function(test, err) {
+   *     console.log('fail: %s -- error: %s', test.fullTitle(), err.message);
+   *   });
+   *
+   *   runner.on(EVENT_TEST_END, function() {
+   *     console.log('end: %d/%d', runner.stats.passes, runner.stats.tests);
+   *   });
+   * }
+   *
+   * module.exports = MyReporter;
+   *
    * @public
    * @memberof Runner
    * @readonly
@@ -97,7 +129,13 @@ var constants = utils.defineConstants(
      */
     EVENT_TEST_END: 'test end',
     /**
-     * Emitted when {@link Test} execution fails
+     * Emitted when {@link Test} execution fails. Includes an `err` object of type `Error`.
+     * @example
+     * runner.on(EVENT_TEST_FAIL, function(test, err) {
+     *   console.log('fail: %s -- error: %s', test.fullTitle(), err.message);
+     * });
+     *
+     *
      */
     EVENT_TEST_FAIL: 'fail',
     /**