Why does a Mocha test suite pass locally but fail in CI when using the --exit flag?

Direct Answer

The --exit flag does not change test outcomes; it only forces process.exit() after the reporter finishes instead of waiting for the event loop to drain. If the suite passes locally but fails in CI with --exit, the failure is almost always a real test failure (timeout, unhandled rejection, or config difference) that --exit surfaces by terminating the process immediately rather than letting it hang.

Confirmed Causes

1. Timeouts: CI runners are slower or contended. The default 2000 ms timeout that never fires locally is exceeded in CI. Fix by raising the timeout (--timeout 10000) or optimizing the slow operation.
2. Unhandled promise rejections: Modern Node (≥15) treats unhandled rejections as fatal errors by default. Older local Node versions or different flags (--unhandled-rejections=warn) may only warn. Pin the Node version in CI (e.g., .nvmrc or container tag) to match local.
3. Configuration drift: CLI flags override everything. package.json mocha object or .mocharc.* apply when CLI doesn't specify. The legacy test/mocha.opts was removed in Mocha 8; if CI and local run different Mocha majors, the same mocha.opts is silently ignored in one environment. MOCHA_OPTS is not read by Mocha itself—it only takes effect if your CI script explicitly passes it (e.g., mocha $MOCHA_OPTS).

Likely Explanation (Verify First)

Your CI failure is probably a timeout or unhandled rejection that --exit reveals by cutting off the process before you see the full stack trace locally. Without --exit, the local process would hang on the same lingering handles, making the problem invisible.

Minimal Diagnostic Steps

1. Print versions in CI and compare locally:

   node --version
   npx mocha --version

2. Run locally without --exit. If the process hangs, list open handles to find the leak:

   node --trace-warnings ./node_modules/.bin/mocha

3. Confirm rejection handling in CI:

   node --unhandled-rejections=strict -e "Promise.reject(new Error('test'))"

4. Diff effective config: check CI command line, package.json scripts, and any wrapper for injected flags or MOCHA_OPTS usage.

One Missing Detail

What exact Node and Mocha versions run in CI vs. locally? Version drift is the single most common hidden cause and changes whether you need a timeout bump, a rejection-handling fix, or a config alignment.