Limits: Mocha's --delay Option and Async/Await Execution

Answer

With --delay Mocha does not start any test until you explicitly invoke mocha.run(). Therefore an async/await test function is not executed – and cannot begin awaiting – until after that call, so the delay correctly pauses the test.

Confirmed facts

• Mocha 9.x+ with --delay returns control to the test file; the test runner stays idle until mocha.run() is called.
• Test hooks (before, after, it) only run after mocha.run().
• If an async test does not return a promise or accept a done callback, Mocha treats it as synchronous and may finish before the async work completes, leading to false passes or timeouts.
• To use async/await safely with --delay, each test must either return a promise or take a done argument, and you should call mocha.run() after all top‑level await code has finished (typically at the end of the file).

Interaction with --grep

The --grep filter is applied when mocha.run() starts; it selects which tests to execute. The delay flag does not change this selection, so combining --delay and --grep works exactly as --grep alone – only matching tests are run after you invoke mocha.run(). No extra skipping occurs.

Steps for reliable alert‑noise suppression

1. Start Mocha with --delay (e.g., mocha --delay test/**/*.spec.js).
2. In your test file, keep any top‑level setup that must happen before tests as plain synchronous code or await it before calling mocha.run().
3. Write each test as an async function that returns a promise (or accepts done). Example:

// test/example.spec.js
const assert = require('assert');

async function delaySetup() {
  // any async work needed before tests
  await new Promise(r => setTimeout(r, 10));
}

delaySetup().then(() => {
  // This runs after top‑level await finishes
  mocha.run();
});

describe('Async suite', function () {
  it('should resolve', async function () {
    const val = await Promise.resolve(42);
    assert.strictEqual(val, 42);
  });

  it('should reject', async function () {
    await assert.rejects(Promise.reject(new Error('fail')));
  });
});

With this pattern the test process will stay silent until you explicitly call mocha.run(), preventing any test output (including notification noise) from appearing before you are ready.

When the recommendation might change

If you are using a custom reporter that writes to stdout/stderr during hook execution, the delay will still suppress test output but reporter initialization may still produce noise. In that case, let me know which reporter you are using so I can suggest a quiet alternative.