Sequential `hardhat test` intermittently dies with exit 1 on a rejection that was actually handled

[ChristopherDedominici]

Version of Hardhat

3.9.1

What happened?

What's happening

This hits any sequential test run — anything not using mocha's parallel: true. Sequential is the default, so a plain hardhat test is already exposed; and --coverage is always exposed because coverage can't run in parallel at all (parallel mode is the only safe one — it's not about coverage). When it triggers, the whole run suddenly dies with exit 1 and prints something like:

Unhandled promise rejection:
SolidityError: VM Exception ... reverted with reason string 'AccessControl: ...'

The annoying part: that revert is expected — it's a passing "this should revert" test. No test actually failed. And it's intermittent: editing unrelated test files earlier in the run flips it on and off, because it's a timing race.

Why it happens

When lots of tests do something similar to this:

await expect(contract.connect(stranger).setFoo(1)) // ← tx starts, can reject here
  .to.be.revertedWithOZAccessControlError(
    stranger.address,
    await contract.FOO_ROLE(), // ← this RPC call runs BEFORE the matcher attaches
  );

Between the tx starting and the matcher attaching (during that await contract.FOO_ROLE()), the tx promise has no .catch on it yet. If the expected revert lands in that gap, Node fires unhandledRejection. The matcher attaches a tick later and catches it just fine — Node even fires rejectionHandled to say "never mind, it got handled."

But Hardhat's CLI installs a global unhandledRejection handler at startup that just does process.exit(1) and never listens for rejectionHandled. In sequential mode mocha runs in that same process, so the handler is still armed and kills the run before the "never mind" arrives.

Parallel mode doesn't have this problem because tests run in mocha worker processes that never install that handler.

High-level fix

While a sequential (in-process) mocha run is active, swap the CLI's fail-fast unhandledRejection handler for a smarter one:

• on unhandledRejection → park it instead of exiting
• on rejectionHandled → release it (a matcher caught it late — all good)
• when the run ends → anything still parked is a real never-handled bug → exit 1 and report it

Everything else stays the same: parallel mode untouched, hardhat node/scripts keep fail-fast, and genuinely unhandled rejections still fail the run.

Minimal reproduction steps

Repro

Add this test and run it sequentially (no parallel: true):

import { expect } from "chai";

describe("unhandled-rejection tolerance", () => {
  it("survives a rejection handled one tick later", async () => {
    const doomed = Promise.reject(new Error("expected revert")); // tx promise, no handler yet
    await new Promise((r) => setTimeout(r, 10)); // the `await contract.ROLE()` gap
    await doomed.catch((e) => expect(e.message).to.equal("expected revert")); // matcher attaches late
  });
});

Search terms

No response

[nishant-uxs]

Proposal to implement (external contributor)

Hi @ChristopherDedominici — I noticed you're assigned here. I couldn't find an open PR or WIP branch for this issue (searched for 8432 / unhandledRejection / rejectionHandled). If you're already working on it, please say so and I'll stand down.

If not, I'd like to open a PR that follows the approach already outlined in this issue:

Design

1. Keep CLI fail-fast unhandledRejection → process.exit(1) for all non-test / parallel paths.
2. During sequential in-process Mocha only (hardhat-mocha task when parallel !== true, which also covers --coverage), temporarily switch to deferred mode:
   • unhandledRejection → park (promise → reason) instead of exiting
   • rejectionHandled → drop that promise from the park
   • after Mocha finishes → if anything is still parked, print and exit(1); otherwise continue normally
3. Parallel Mocha workers are unchanged (they never install the CLI handlers).
4. No new user-facing config.

API surface

Export a small internal helper from hardhat (same pattern as hardhat/internal/coverage) so hardhat-mocha can enable/flush deferred mode around the sequential mocha.run() without env-var coupling.

Tests

• Fixture: late-handled rejection survives sequential CLI run (exit 0)
• Fixture: truly unhandled rejection still fails sequential CLI run (exit 1)
• Parallel mode still green with the same late-handled pattern
• Coverage path inherits sequential deferred mode (no parallel)
• Unit tests for park / rejectionHandled / flush on the handler module

Does this match what you had in mind? Happy to adjust before/after review.

[kanej]

Hey @nishant-uxs, I think Chris intends to tackle this one.

[nishant-uxs]

Thanks @kanej — standing down. Will leave this for Chris.