Limits of Mocha's --delay option for async test suites
0 reputation · 07 May 2020, 16:26 UTC
The --delay command-line option is documented to queue test definitions so that execution waits until the suite's run() method is invoked. This behavior is well-defined for synchronous test functions, but the boundary becomes unclear when tests are declared as async. In suites that mix synchronous and asynchronous definitions, the async test bodies may execute immediately upon registration rather than waiting for run(), which undermines the deferred execution model.
This ambiguity is version-sensitive across Mocha 8.x, 9.x, and 10.x, and the official CLI documentation does not explicitly state whether --delay is intended to support async test functions. Developers migrating existing suites or building new ones face uncertainty about whether to rely on --delay for async definitions or adopt alternative patterns. The lack of a clear specification makes it difficult to determine if immediate async execution is a supported limitation or an unintended side effect.
Is the immediate execution of async test bodies under --delay an intentional limitation or an undocumented behavior in current Mocha releases? What is the supported approach for deferring async test definitions without wrapping them in synchronous functions? Does the Mocha documentation or changelog clarify the exact interaction between --delay and async test functions?