## TL;DR
In parallel mode mocha loads your test files inside worker processes, and anything that assumes a single shared process breaks: global state, in-memory singletons, port collisions, and files that only run correctly when loaded once. The usual fix is to make each test file self-contained (its own setup/teardown, no cross-file globals) and to give workers distinct resources (ephemeral ports, isolated temp dirs). Start by running one failing file alone in parallel mode to isolate the culprit.

## The query
```text
mocha parallel mode tests failing: worker file issue
```

## Use this when
- Tests pass with plain `mocha` but fail with `mocha --parallel`
- Workers crash or files report "file did not load" style errors
- You see port-in-use errors only in parallel runs
- Parallel runs are flaky while serial runs are stable

## Not for
- Mocha installation or basic config problems
- Assertion failures that happen serially too
- Speeding up non-mocha runners

## Steps
1. Run a single suspect file in parallel mode (`npx mocha --parallel path/to/file.spec.js`) and note the exact error. Expected output: the error reproduces with one file, proving it is a load/loading issue rather than cross-file interference.
2. Check the file's top-level code for process-global side effects: servers binding fixed ports, singleton DB connections, `process.env` mutation, or `require` cache assumptions. Expected output: you find at least one resource that cannot be safely duplicated across workers.
3. Make the file self-contained: bind ephemeral ports (port 0), create fresh clients per file, and move shared fixtures into `before`/`after` hooks instead of module top-level. Expected output: the single file passes in parallel mode.
4. Re-run the full suite in parallel and compare failures to the serial baseline. Expected output: parallel run is green, or remaining failures match the serial run (real bugs, not parallelism bugs).

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_VNiKhY28Y2NYwv0ILLshyA