feat: add --fail-hook-affected-tests option to report skipped tests as failed

When `before()` or `beforeEach()` hooks fail, Mocha currently only reports
the hook failure and silently skips affected tests. This makes it difficult
to track test coverage and understand the full impact of hook failures.

This change introduces a new CLI option `--fail-hook-affected-tests` that,
when enabled, reports all tests affected by hook failures as failed instead
of silently skipping them.

Changes:
- Added --fail-hook-affected-tests boolean CLI option
- Implemented failAffectedTests() method in Runner to fail all affected tests
- Updated hook() method to call failAffectedTests when hooks fail
- Added failHookAffectedTests option to Mocha class
- Added integration tests for both before() and beforeEach() hook failures
- All affected tests now receive descriptive error messages indicating
  which hook caused them to be skipped

Fixes #4392

Author: claude

lib/cli/run-option-metadata.js

@@ -35,6 +35,7 @@ const TYPES = (exports.types = {
     "diff",
     "dry-run",
     "exit",
+    "fail-hook-affected-tests",
     "pass-on-failing-test-suite",
     "fail-zero",
     "forbid-only",

lib/cli/run.js

@@ -103,6 +103,11 @@ exports.builder = (yargs) =>
         description: "Not fail test run if tests were failed",
         group: GROUPS.RULES,
       },
+      "fail-hook-affected-tests": {
+        description:
+          "Report tests as failed when affected by hook failures (before/beforeEach)",
+        group: GROUPS.RULES,
+      },
       "fail-zero": {
         description: "Fail test run if no test(s) encountered",
         group: GROUPS.RULES,

lib/mocha.js

@@ -847,6 +847,11 @@ Mocha.prototype.dryRun = function (dryRun) {
  * @return {Mocha} this
  * @chainable
  */
+Mocha.prototype.failHookAffectedTests = function (failHookAffectedTests) {
+  this.options.failHookAffectedTests = failHookAffectedTests !== false;
+  return this;
+};
+
 Mocha.prototype.failZero = function (failZero) {
   this.options.failZero = failZero !== false;
   return this;
@@ -966,6 +971,7 @@ Mocha.prototype.run = function (fn) {
     cleanReferencesAfterRun: this._cleanReferencesAfterRun,
     delay: options.delay,
     dryRun: options.dryRun,
+    failHookAffectedTests: options.failHookAffectedTests,
     failZero: options.failZero,
   });
   createStatsCollector(runner);

lib/runner.js

@@ -182,6 +182,7 @@ class Runner extends EventEmitter {
    * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
    * @param {boolean} [opts.dryRun] - Whether to report tests without running them.
    * @param {boolean} [opts.failZero] - Whether to fail test run if zero tests encountered.
+   * @param {boolean} [opts.failHookAffectedTests] - Whether to fail all tests affected by hook failures.
    */
   constructor(suite, opts = {}) {
     super();
@@ -441,6 +442,47 @@ Runner.prototype.checkGlobals = function (test) {
   }
 };
 
+/**
+ * Fail all tests that are affected by a hook failure.
+ * This is used when the `failHookAffectedTests` option is enabled.
+ *
+ * @private
+ * @param {Suite} suite - The suite containing the affected tests
+ * @param {Error} hookError - The error from the failed hook
+ * @param {string} hookTitle - The title of the failed hook
+ */
+Runner.prototype.failAffectedTests = function (suite, hookError, hookTitle) {
+  if (!this._opts.failHookAffectedTests) {
+    return;
+  }
+
+  var self = this;
+  var errorMessage =
+    'Test skipped due to failure in "' + hookTitle + '": ' + hookError.message;
+  var testError = new Error(errorMessage);
+  testError.stack = hookError.stack;
+
+  // Recursively fail all tests in this suite and its child suites
+  function failTestsInSuite(s) {
+    s.tests.forEach(function (test) {
+      // Only fail tests that haven't been executed yet
+      if (!test.state) {
+        test.state = STATE_FAILED;
+        self.failures++;
+        self.emit(constants.EVENT_TEST_BEGIN, test);
+        self.emit(constants.EVENT_TEST_FAIL, test, testError);
+        self.emit(constants.EVENT_TEST_END, test);
+      }
+    });
+
+    s.suites.forEach(function (childSuite) {
+      failTestsInSuite(childSuite);
+    });
+  }
+
+  failTestsInSuite(suite);
+};
+
 /**
  * Fail the given `test`.
  *
@@ -583,6 +625,34 @@ Runner.prototype.hook = function (name, fn) {
         }
       } else if (err) {
         self.fail(hook, err);
+        // If failHookAffectedTests is enabled, mark affected tests as failed
+        if (self._opts.failHookAffectedTests) {
+          if (name === HOOK_TYPE_BEFORE_ALL) {
+            self.failAffectedTests(self.suite, err, hook.title);
+          } else if (name === HOOK_TYPE_BEFORE_EACH) {
+            // Fail the current test
+            if (self.test && !self.test.state) {
+              var errorMessage =
+                'Test skipped due to failure in "' +
+                hook.title +
+                '": ' +
+                err.message;
+              var testError = new Error(errorMessage);
+              testError.stack = err.stack;
+
+              self.test.state = STATE_FAILED;
+              self.failures++;
+              self.emit(constants.EVENT_TEST_BEGIN, self.test);
+              self.emit(constants.EVENT_TEST_FAIL, self.test, testError);
+              self.emit(constants.EVENT_TEST_END, self.test);
+            }
+            // Store the hook error info for remaining tests
+            self._failedBeforeEachHook = {
+              error: err,
+              title: hook.title,
+            };
+          }
+        }
         // stop executing hooks, notify callee of hook err
         return fn(err);
       }
@@ -734,10 +804,40 @@ Runner.prototype.runTests = function (suite, fn) {
   var tests = suite.tests.slice();
   var test;
 
-  function hookErr(_, errSuite, after) {
+  function hookErr(err, errSuite, after) {
     // before/after Each hook for errSuite failed:
     var orig = self.suite;
 
+    // If failHookAffectedTests is enabled and this is a beforeEach failure,
+    // mark remaining tests as failed
+    if (
+      self._opts.failHookAffectedTests &&
+      !after &&
+      self._failedBeforeEachHook
+    ) {
+      // Fail all remaining tests in the suite
+      var remainingTests = tests.slice();
+      remainingTests.forEach(function (t) {
+        if (!t.state) {
+          var errorMessage =
+            'Test skipped due to failure in "' +
+            self._failedBeforeEachHook.title +
+            '": ' +
+            self._failedBeforeEachHook.error.message;
+          var testError = new Error(errorMessage);
+          testError.stack = self._failedBeforeEachHook.error.stack;
+
+          t.state = STATE_FAILED;
+          self.failures++;
+          self.emit(constants.EVENT_TEST_BEGIN, t);
+          self.emit(constants.EVENT_TEST_FAIL, t, testError);
+          self.emit(constants.EVENT_TEST_END, t);
+        }
+      });
+      // Clear the stored hook info
+      delete self._failedBeforeEachHook;
+    }
+
     // for failed 'after each' hook start from errSuite parent,
     // otherwise start from errSuite itself
     self.suite = after ? errSuite.parent : errSuite;

test/integration/fixtures/hooks/before-each-hook-error-with-fail-affected.fixture.js

@@ -0,0 +1,18 @@
+'use strict';
+
+describe('spec 1', function () {
+  beforeEach(function () {
+    throw new Error('before each hook error');
+  });
+  it('test 1', function () {
+    // This should be reported as failed due to beforeEach hook failure
+  });
+  it('test 2', function () {
+    // This should be reported as failed due to beforeEach hook failure
+  });
+});
+describe('spec 2', function () {
+  it('test 3', function () {
+    // This should pass normally
+  });
+});

test/integration/fixtures/hooks/before-hook-error-with-fail-affected.fixture.js

@@ -0,0 +1,18 @@
+'use strict';
+
+describe('spec 1', function () {
+  before(function () {
+    throw new Error('before hook error');
+  });
+  it('test 1', function () {
+    // This should be reported as failed due to before hook failure
+  });
+  it('test 2', function () {
+    // This should be reported as failed due to before hook failure
+  });
+});
+describe('spec 2', function () {
+  it('test 3', function () {
+    // This should pass normally
+  });
+});

test/integration/hook-err.spec.js

@@ -267,6 +267,52 @@ describe("hook error handling", function () {
     });
   });
 
+  describe("--fail-hook-affected-tests", function () {
+    describe("before hook error", function () {
+      it("should fail all affected tests", function (done) {
+        runMochaJSON(
+          "hooks/before-hook-error-with-fail-affected",
+          ["--fail-hook-affected-tests"],
+          (err, res) => {
+            if (err) {
+              return done(err);
+            }
+            expect(res, "to have failed")
+              .and("to have failed test count", 3)
+              .and("to have failed test", '"before all" hook for "test 1"')
+              .and("to have failed test", "test 1")
+              .and("to have failed test", "test 2")
+              .and("to have passed test count", 1)
+              .and("to have passed test", "test 3");
+            done();
+          },
+        );
+      });
+    });
+
+    describe("beforeEach hook error", function () {
+      it("should fail all affected tests", function (done) {
+        runMochaJSON(
+          "hooks/before-each-hook-error-with-fail-affected",
+          ["--fail-hook-affected-tests"],
+          (err, res) => {
+            if (err) {
+              return done(err);
+            }
+            expect(res, "to have failed")
+              .and("to have failed test count", 3)
+              .and("to have failed test", '"before each" hook for "test 1"')
+              .and("to have failed test", "test 1")
+              .and("to have failed test", "test 2")
+              .and("to have passed test count", 1)
+              .and("to have passed test", "test 3");
+            done();
+          },
+        );
+      });
+    });
+  });
+
   function run(fnPath, outputFilter) {
     return (done) =>
       runMocha(fnPath, ["--reporter", "dot"], (err, res) => {