Mocha async test timeouts: distinguishing late rejections from hanging promises

Mocha Timeout Behavior for Async Tests

Mocha cannot differentiate a promise that rejects after the deadline from one that hangs indefinitely; once the timeout expires it aborts the test and reports a generic timeout error, losing the original rejection reason.

Timeout Budget Scope

The timeout budget is set once when this.timeout(ms) is called (or via the --timeout CLI flag) and applies to the entire test function. It does not reset at each await statement, so all sequential awaited operations share the same budget.

Placement of this.timeout()

Place this.timeout(ms) as the first statement inside the it block, before any asynchronous call. If placed later, the initial async operation is still governed by the default timeout. The setting also works in before, after, beforeEach and afterEach hooks, but hooks do not inherit the timeout value from the surrounding it block.

• Inside it blocks: declare this.timeout() at the very start of the function body.
• Inside hooks: the timeout applies only to that hook’s execution; it does not affect the surrounding test’s overall budget.

Verification Steps

To confirm the behavior, create a minimal test:

it('shows timeout priority', function() { 
  this.timeout(100); 
  // Rejection occurs after 150ms but test fails at 100ms 
  setTimeout(() => { 
    // would resolve with a rejection reason 
  }, 150); 
});

The runner will emit a Timeout of 100ms exceeded error, not the rejection message.

If you need to capture a late rejection, wrap the async work in a Promise.race() with a timer and handle the rejection manually; Mocha’s timeout configuration cannot be altered to preserve post‑deadline rejections.

Note: Mocha’s timeout handling may vary between major versions (e.g., 8.x vs 10.x). Verify the version you are using to ensure the described behavior matches your environment.

Missing Diagnostic

Please indicate which Mocha major version you are running, as timeout semantics can differ across releases.