Limits of Mocha's --delay option for async test suites

Direct answer

The immediate execution of async test bodies under --delay is a longstanding, expected limitation across Mocha 8.x, 9.x, and 10.x, not an undocumented bug. --delay postpones the root suite's run loop and pending hooks; it does not intercept the registration phase where test callbacks are invoked. When Mocha loads a test file, it walks the suite tree and calls each test function to capture its return value. For an async function, that call starts the promise chain immediately, so any await, timer, or I/O inside the body begins before run() is invoked.

Confirmed behavior vs. inferred mechanics

The following are well-established from Mocha's documented interface:

• --delay is documented as delaying root suite execution, with no mention of special handling for async functions.
• The flag gates the runner's start and pending root hooks, not the evaluation of test callbacks during require.
• Sync test bodies are fully executed during registration, which is why they appear to wait for run().
• Official documentation and changelog entries across these versions do not describe special handling for async functions under --delay, indicating the limitation is longstanding rather than a recent regression.

The precise source-level mechanism is consistent with observed behavior, though exact implementation details should be verified against your installed version. This summary reflects documented behavior and long-standing community understanding across Mocha 8–10; check the changelog for your exact build if you are on a patched or pre-release version.

Supported approach for deferring async definitions

Mocha does not provide a supported way to defer async test definitions without synchronous indirection. The --delay flag is scoped to the run loop, not registration. If async setup must wait for an explicit trigger, move it into a root before hook, which is deferred because hooks are part of the runnable suite. Alternatively, generate tests inside a synchronous describe callback and call run() from your own bootstrap logic. Wrapping the async body in a synchronous factory that returns an async function is the closest pattern, but it still requires a synchronous outer function at registration time.

Verification steps

1. Create a file with one sync test and one async test that each log a timestamp.
2. Run mocha --delay ./test.js and observe that the async log appears before the delayed start message.
3. Remove --delay and confirm both tests log after the runner starts.

One diagnostic detail that changes the recommendation

If the async work is in top-level await during file loading rather than inside an it() callback, state that explicitly. Top-level await executes before Mocha can apply any delay, which changes the recommendation from a wrapper pattern to restructuring the file load.