Mocha async timeout precedence between global configuration and per-test overrides in ESM modules

Answer

The documented precedence is: test‑level this.timeout() > suite‑level this.timeout() > CLI --timeout flag (or global config) > Mocha’s built‑in default of 2000 ms.

Confirmed facts

• Mocha resolves timeout values by walking outward from the test context; the most specific value wins.
• For async/await tests you must use a regular function() test callback so that this refers to the Mocha test context; arrow functions do not bind this and the call is ignored.
• A rejected promise or thrown error fails the test immediately; the timeout timer only matters when the test remains pending after the async work settles.
• The slow() threshold is purely for reporting and does not affect pass/fail or timeout enforcement.
• Across Node 18, 20 and 22 the timeout precedence stays the same; only the default handling of unhandled rejections changed (e.g., Node 15+ treats unhandled rejections as fatal unless a listener is present), which can cause the process to exit before Mocha reports a timeout.

Verification steps (minimal)

1. Create an ESM test file test/timeout.mjs with a suite and a test:

import { describe, it } from 'mocha';

describe('timeout suite', function () {
  this.timeout(150); // suite‑level

  it('should respect test timeout', function () {
    this.timeout(50); // test‑level
    return new Promise(res => setTimeout(res, 200)); // longer than test timeout
  });
});

2. Run with a CLI timeout different from both: mocha --timeout 500 test/timeout.mjs
3. Observe that the test fails after ~50 ms, confirming test‑level overrides suite and CLI.
4. Repeat removing the test‑level call; the failure should occur near the suite value (150 ms).
5. Repeat removing both suite and test calls; the failure should occur near the CLI value (500 ms) or the default 2000 ms if no CLI flag is given.

Missing diagnostic detail

If you need to confirm that unhandled rejections are not being converted to timeouts on your Node version, run node --version and mocha --version and check whether --unhandled-rejections=strict or similar flags are in effect; this can change whether a rejected promise aborts the process before Mocha’s timeout fires.