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

[akshah123]

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

PR Checklist

• [x] Addresses an existing open issue: fixes #4392
• [x] That issue was marked as status: accepting prs
• [x] Steps in CONTRIBUTING.md were taken

Overview

[linux-foundation-easycla[bot]]

• :white_check_mark: login: akshah123 / name: Ankit Shah (1feba532e9ae5f43c8b8cadc8f5209ba0227d45f, 300b485bd6c1c84d4becca542d1b62dcf528df50, 9fe8493b322c9886a93efc1c784c2725f1a73310, c171cf110b1de5a63678093e2d9c75e267b55ed0)
• :x: - login: @claude / name: Claude . The commit (6d3d64ea80252546302ecaddbc7c57718ac79c55) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.

[mark-wiemer]

Hmm, I think we can ignore the CLA issue as the non-signer is AI :D

[mark-wiemer]

I'll review this in more detail sometime in the next ~7 days :)

[codecov[bot]]

Codecov Report

:x: Patch coverage is 92.59259% with 4 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 93.51%. Comparing base (2a0bce0) to head (300b485). :warning: Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/mocha.js	33.33%	2 Missing :warning:
lib/runner.js	96.07%	2 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5519      +/-   ##
==========================================
- Coverage   93.69%   93.51%   -0.18%     
==========================================
  Files          57       57              
  Lines        4391     4518     +127     
  Branches      850      931      +81     
==========================================
+ Hits         4114     4225     +111     
- Misses        277      293      +16     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mark-wiemer]

Took me a minute to remember I needed to actively add the --fail-hook-affected-tests flag to see the new behavior :D was able to repro locally and the code does look good. Going to wait for @JoshuaKGoldberg to review, hopefully early next week.

[akshah123]

@JoshuaKGoldberg Thanks for the thorough review! I've addressed both of your comments in the latest commit (c171cf11):

Re: [Docs] JSDoc placement - Fixed! The JSDoc now correctly documents failHookAffectedTests and has been separated from failZero's documentation. Each function now has its own properly positioned JSDoc comment.

Re: [Bug] Non-Error handling - Great catch! The createHookSkipError function now properly handles:

• Falsy values (null/undefined) using createInvalidExceptionError
• Non-Error objects (strings, numbers, etc.) using thrown2Error

This follows the existing patterns from runner.js:1112 and runner.js:537. I've also added comprehensive test coverage for these edge cases with new fixture files testing null, undefined, string, and number throws in both before and beforeEach hooks.

All tests are passing, including the 2 new integration tests specifically for non-Error handling. ✅

[mark-wiemer]

@akshah123 looks like your latest commit broke some stuff, please review the failed checks.

@JoshuaKGoldberg happy to port this back to v11, created #5580

[akshah123]

Sorry about that @mark-wiemer . I didn't verify syntax issues with suggested changes. It should be fixed now.