Where Does Mocha Store Its Config?
Mocha reads .mocharc files by extension priority, then the package.json mocha key, under CLI args and MOCHA_OPTIONS.
Last updated
Mocha layers five sources: CLI flags, MOCHA_OPTIONS env, one rc file (.mocharc.cjs down to .mocharc.json by priority), the mocha key in package.json, then built-in defaults. Repeatable flags like --require concatenate down the chain instead of overriding.
The spec gotcha bites hardest: positional args append to (not replace) a spec list from config, so stray patterns keep running suites you thought excluded. Comment out spec or point --config elsewhere when scoping a run.
Where Mocha stores this, by platform
[RepoDir]\.mocharc.json
Reporter, timeout, spec globs, require hooks. --package relocates package.json lookup; one-and-done flags skip file discovery entirely.
[RepoDir]/.mocharc.json
Same order. ESM projects prefer .mocharc.cjs (or .mjs) to dodge module type fights with the surrounding package.json.
[RepoDir]/.mocharc.json
Same layout. MOCHA_OPTIONS injects flags for every run, handy for global --reporter tweaks without touching shared files.
Frequently asked questions
I have .mocharc.json and .mocharc.yml. Which applies?
Only one file loads: the highest priority match (.mocharc.cjs first, .mocharc.json last). Split variants never merge, so consolidate into one file or select explicitly with --config.
How do I run Mocha ignoring all config files?
Pass mocha --no-config (and --no-package to skip package.json too). CI uses this to enforce flag-only runs that no committed file can perturb.
Notice an outdated path? Let us know.