From 889387025ee0d48786674c342bce548afc2ac918 Mon Sep 17 00:00:00 2001
From: Mark Wiemer <markwiemer@outlook.com>
Date: Fri, 3 Jan 2025 07:17:59 -0800
Subject: [PATCH] Document usages of `Runner.constants`

---
 lib/runner.js | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/lib/runner.js b/lib/runner.js
index ad31843444..7a76cb8155 100644
--- 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',
     /**